X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fos-release.xml;h=b2983049432bbb29f2fcac14f0b433ceb192b9f3;hp=045dd08f1f899b520921e3134a596e91e1c8af53;hb=e0104622b33f39ea8fd54f0a286d938401c08e3d;hpb=6ed80a4e346883b99263a1a13505ef6afcbc09c3

diff --git a/man/os-release.xml b/man/os-release.xml
index 045dd08f1..b29830494 100644
--- a/man/os-release.xml
+++ b/man/os-release.xml
@@ -49,20 +49,22 @@
 
         <refsynopsisdiv>
                 <para><filename>/etc/os-release</filename></para>
+                <para><filename>/usr/lib/os-release</filename></para>
         </refsynopsisdiv>
 
         <refsect1>
                 <title>Description</title>
 
-                <para>The <filename>/etc/os-release</filename> file
-                contains operating system identification data.</para>
+                <para>The <filename>/etc/os-release</filename> and
+                <filename>/usr/lib/os-release</filename> files contain
+                operating system identification data.</para>
 
                 <para>The basic file format of
                 <filename>os-release</filename> is a newline-separated
                 list of environment-like shell-compatible variable
                 assignments. It is possible to source the
                 configuration from shell scripts, however, beyond mere
-                variable assignments no shell features are supported
+                variable assignments, no shell features are supported
                 (this means variable expansion is explicitly not
                 supported), allowing applications to read the file
                 without implementing a shell compatible execution
@@ -72,26 +74,48 @@
                 a-z, 0-9. All strings should be in UTF-8 format, and
                 non-printable characters should not be used. If double
                 or single quotes or backslashes are to be used within
-                variable assignments they should be escaped with
+                variable assignments, they should be escaped with
                 backslashes, following shell style. It is not
                 supported to concatenate multiple individually quoted
                 strings. Lines beginning with "#" shall be ignored as
                 comments.</para>
 
-                <para><filename>/etc/os-release</filename> contains
-                data that is defined by the operating system vendor
-                and should not be changed by the administrator.</para>
+                <para>The file <filename>/etc/os-release</filename>
+                takes precedence over
+                <filename>/usr/lib/os-release</filename>. Applications
+                should check for the former, and exclusively use its
+                data if it exists, and only fall back to
+                <filename>/usr/lib/os-release</filename> if it is
+                missing. Applications should not read data from both
+                files at the same
+                time. <filename>/usr/lib/os-release</filename> is the
+                recommended place to store OS release information as
+                part of vendor trees.
+                <filename>/etc/os-release</filename> should be a
+                relative symlink to
+                <filename>/usr/lib/os-release</filename>,
+                to provide compatibility with applications only
+                looking at <filename>/etc</filename>. A relative
+                symlink instead of an absolute symlink is
+                necessary to avoid breaking the link in a chroot or
+                initrd environment such as dracut.</para>
+
+                <para><filename>os-release</filename> contains data
+                that is defined by the operating system vendor and
+                should generally not be changed by the
+                administrator.</para>
 
                 <para>As this file only encodes names and identifiers
                 it should not be localized.</para>
 
-                <para>The file <filename>/etc/os-release</filename> might
-                be a symlink to another file, but it is important that
+                <para>The <filename>/etc/os-release</filename> and
+                <filename>/usr/lib/os-release</filename> files might
+                be symlinks to other files, but it is important that
                 the file is available from earliest boot on, and hence
                 must be located on the root file system.</para>
 
                 <para>For a longer rationale for
-                <filename>/etc/os-release</filename> please refer to
+                <filename>os-release</filename> please refer to
                 the <ulink
                 url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
         </refsect1>
@@ -100,7 +124,7 @@
                 <title>Options</title>
 
                 <para>The following OS identifications parameters may be set using
-                <filename>/etc/os-release</filename>:</para>
+                <filename>os-release</filename>:</para>
 
                 <variablelist>
 
@@ -110,7 +134,7 @@
                                 <listitem><para>A string identifying
                                 the operating system, without a
                                 version component, and suitable for
-                                presentation to the user. If not set
+                                presentation to the user. If not set,
                                 defaults to
                                 <literal>NAME=Linux</literal>. Example:
                                 <literal>NAME=Fedora</literal> or
@@ -143,7 +167,7 @@
                                 excluding any version information and
                                 suitable for processing by scripts or
                                 usage in generated filenames. If not
-                                set defaults to
+                                set, defaults to
                                 <literal>ID=linux</literal>. Example:
                                 <literal>ID=fedora</literal> or
                                 <literal>ID=debian</literal>.</para></listitem>
@@ -155,7 +179,7 @@
                                 <listitem><para>A space-separated list
                                 of operating system identifiers in the
                                 same syntax as the
-                                <varname>ID=</varname> setting. Should
+                                <varname>ID=</varname> setting. It should
                                 list identifiers of operating systems
                                 that are closely related to the local
                                 operating system in regards to
@@ -165,8 +189,8 @@
                                 OS is a derivative from. An
                                 OS should generally only list other OS
                                 identifiers it itself is a derivative
-                                from, and not any OSes that
-                                are derived from it, but symmetric
+                                of, and not any OSes that
+                                are derived from it, though symmetric
                                 relationships are possible. Build
                                 scripts and similar should check this
                                 variable if they need to identify the
@@ -179,11 +203,11 @@
                                 closest. This field is
                                 optional. Example: for an operating
                                 system with
-                                <literal>ID=centos</literal> an
+                                <literal>ID=centos</literal>, an
                                 assignment of <literal>ID_LIKE="rhel
                                 fedora"</literal> would be
                                 appropriate. For an operating system
-                                with <literal>ID=ubuntu</literal> an
+                                with <literal>ID=ubuntu</literal>, an
                                 assignment of
                                 <literal>ID_LIKE=debian</literal> is
                                 appropriate.</para></listitem>
@@ -213,7 +237,7 @@
                                 presentation to the user. May or may
                                 not contain a release code name or OS
                                 version of some kind, as suitable. If
-                                not set defaults to
+                                not set, defaults to
                                 <literal>PRETTY_NAME="Linux"</literal>. Example:
                                 <literal>PRETTY_NAME="Fedora 17 (Beefy
                                 Miracle)"</literal>.</para></listitem>
@@ -290,7 +314,7 @@
                                 <literal>tel:</literal>. Only one URL
                                 shall be listed in each setting. If
                                 multiple resources need to be
-                                referenced it is recommended to
+                                referenced, it is recommended to
                                 provide an online landing page linking
                                 all available resources. Examples:
                                 <literal>HOME_URL="https://fedoraproject.org/"</literal>
@@ -332,7 +356,7 @@
 
                 <para>Note that operating system vendors may choose
                 not to provide version information, for example to
-                accommodate for rolling releases. In this case VERSION
+                accommodate for rolling releases. In this case, VERSION
                 and VERSION_ID may be unset. Applications should not
                 rely on these fields to be set.</para>