chiark / gitweb /
man: wording and grammar updates
[elogind.git] / man / os-release.xml
index 7d79972..045dd08 100644 (file)
@@ -9,16 +9,16 @@
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it
-  under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-  General Public License for more details.
+  Lesser General Public License for more details.
 
-  You should have received a copy of the GNU General Public License
+  You should have received a copy of the GNU Lesser General Public License
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
                 <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
+                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
                 the <ulink
                                 identifying the operating system,
                                 excluding any version information and
                                 suitable for processing by scripts or
-                                usage in generated file names. If not
+                                usage in generated filenames. If not
                                 set defaults to
                                 <literal>ID=linux</literal>. Example:
                                 <literal>ID=fedora</literal> or
                         </varlistentry>
 
                         <varlistentry>
+                                <term><varname>ID_LIKE=</varname></term>
+
+                                <listitem><para>A space-separated list
+                                of operating system identifiers in the
+                                same syntax as the
+                                <varname>ID=</varname> setting. Should
+                                list identifiers of operating systems
+                                that are closely related to the local
+                                operating system in regards to
+                                packaging and programming interfaces,
+                                for example listing one or more
+                                OS identifiers the local
+                                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
+                                relationships are possible. Build
+                                scripts and similar should check this
+                                variable if they need to identify the
+                                local operating system and the value
+                                of <varname>ID=</varname> is not
+                                recognized. Operating systems should
+                                be listed in order of how closely the
+                                local operating system relates to the
+                                listed ones, starting with the
+                                closest. This field is
+                                optional. Example: for an operating
+                                system with
+                                <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
+                                assignment of
+                                <literal>ID_LIKE=debian</literal> is
+                                appropriate.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
                                 <term><varname>VERSION_ID=</varname></term>
 
                                 <listitem><para>A lower-case string
                                 system version, excluding any OS name
                                 information or release code name, and
                                 suitable for processing by scripts or
-                                usage in generated file names. This
+                                usage in generated filenames. This
                                 field is optional. Example:
                                 <literal>VERSION_ID=17</literal> or
                                 <literal>VERSION_ID=11.04</literal>.</para></listitem>
 
                                 <listitem><para>A suggested
                                 presentation color when showing the
-                                distribution name on the console. This
+                                OS name on the console. This
                                 should be specified as string suitable
                                 for inclusion in the ESC [ m
                                 ANSI/ECMA-48 escape code for setting
 
                                 <listitem><para>A CPE name for the
                                 operating system, following the <ulink
-                                url="http://cpe.mitre.org/specification/">Common
+                                url="https://cpe.mitre.org/specification/">Common
                                 Platform Enumeration
                                 Specification</ulink> as proposed by
                                 the MITRE Corporation. This field
                                 <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal>
                                 </para></listitem>
                         </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>HOME_URL=</varname></term>
+                                <term><varname>SUPPORT_URL=</varname></term>
+                                <term><varname>BUG_REPORT_URL=</varname></term>
+
+                                <listitem><para>Links to resources on
+                                the Internet related the operating
+                                system. <varname>HOME_URL=</varname>
+                                should refer to the homepage of the
+                                operating system, or alternatively
+                                some homepage of the specific version
+                                of the operating
+                                system. <varname>SUPPORT_URL=</varname>
+                                should refer to the main support page
+                                for the operating system, if there is
+                                any. This is primarily intended for
+                                operating systems which vendors
+                                provide support
+                                for. <varname>BUG_REPORT_URL=</varname>
+                                should refer to the main bug reporting
+                                page for the operating system, if
+                                there is any. This is primarily
+                                intended for operating systems that
+                                rely on community QA. These settings
+                                are optional, and providing only some
+                                of these settings is common. These
+                                URLs are intended to be exposed in
+                                "About this system" UIs behind links
+                                with captions such as "About this
+                                Operating System", "Obtain Support",
+                                and "Report a Bug". The values should
+                                be in <ulink
+                                url="https://tools.ietf.org/html/rfc3986">RFC3986
+                                format</ulink>, and should be
+                                <literal>http:</literal> or
+                                <literal>https:</literal> URLs, and
+                                possibly <literal>mailto:</literal> or
+                                <literal>tel:</literal>. Only one URL
+                                shall be listed in each setting. If
+                                multiple resources need to be
+                                referenced it is recommended to
+                                provide an online landing page linking
+                                all available resources. Examples:
+                                <literal>HOME_URL="https://fedoraproject.org/"</literal>
+                                and
+                                <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>BUILD_ID=</varname></term>
+
+                                <listitem><para>A string uniquely
+                                identifying the system image used as
+                                the origin for a distribution (it is
+                                not updated with system updates). The
+                                field can be identical between
+                                different VERSION_IDs as BUILD_ID is
+                                an only a unique identifier to a
+                                specific version. Distributions that
+                                release each update as a new version
+                                would only need to use VERSION_ID as
+                                each build is already distinct based
+                                on the VERSION_ID. This field is
+                                optional. Example:
+                                <literal>BUILD_ID="2013-03-20.3"</literal>
+                                or
+                                <literal>BUILD_ID=201303203</literal>.
+
+                                </para></listitem>
+                        </varlistentry>
+
                 </variablelist>
 
                 <para>If you are reading this file from C code or a
                 shell script to determine the OS or a specific version
-                of it, use the ID and VERSION_ID fields. When looking
-                for an OS identification string for presentation to
-                the user use the PRETTY_NAME field.</para>
+                of it, use the ID and VERSION_ID fields, possibly with
+                ID_LIKE as fallback for ID. When looking for an OS
+                identification string for presentation to the user use
+                the PRETTY_NAME field.</para>
 
                 <para>Note that operating system vendors may choose
                 not to provide version information, for example to
                 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>
+
+                <para>Operating system vendors may extend the file
+                format and introduce new fields. It is highly
+                recommended to prefix new fields with an OS specific
+                name in order to avoid name clashes. Applications
+                reading this file must ignore unknown fields. Example:
+                <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>
         </refsect1>
 
         <refsect1>
@@ -228,7 +353,9 @@ ID=fedora
 VERSION_ID=17
 PRETTY_NAME="Fedora 17 (Beefy Miracle)"
 ANSI_COLOR="0;34"
-CPE_NAME="cpe:/o:fedoraproject:fedora:17"</programlisting>
+CPE_NAME="cpe:/o:fedoraproject:fedora:17"
+HOME_URL="https://fedoraproject.org/"
+BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
         </refsect1>
 
         <refsect1>