man: add note about extending machine-info to man page

diff --git a/man/machine-info.xml b/man/machine-info.xml
index c766db2708d28a432f83e0bf3059707a9528b443..cd254a9c355b53fdb3320d229adf29f3106c961c 100644 (file)
--- a/man/machine-info.xml
+++ b/man/machine-info.xml
@@ -53,126 +53,139 @@
     <para>The following machine metadata parameters may be set using
     <filename>/etc/machine-info</filename>:</para>
 
-    <variablelist class='environment-variables'>
-
-      <varlistentry>
-        <term><varname>PRETTY_HOSTNAME=</varname></term>
-
-        <listitem><para>A pretty human-readable UTF-8 machine
-        identifier string. This should contain a name like
-        <literal>Lennart's Laptop</literal> which is useful to present
-        to the user and does not suffer by the syntax limitations of
-        internet domain names. If possible, the internet hostname as
-        configured in <filename>/etc/hostname</filename> should be
-        kept similar to this one. Example: if this value is
-        <literal>Lennart's Computer</literal> an Internet hostname of
-        <literal>lennarts-computer</literal> might be a good choice.
-        If this parameter is not set, an application should fall back
-        to the Internet hostname for presentation
-        purposes.</para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>ICON_NAME=</varname></term>
-
-        <listitem><para>An icon identifying this machine according to
-        the <ulink
-        url="https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
-        Icon Naming Specification</ulink>. If this parameter is not
-        set, an application should fall back to
-        <literal>computer</literal> or a similar icon
-        name.</para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>CHASSIS=</varname></term>
-
-        <listitem><para>The chassis type. Currently, the following
-        chassis types are defined:
-        <literal>desktop</literal>,
-        <literal>laptop</literal>,
-        <literal>convertible</literal>,
-        <literal>server</literal>,
-        <literal>tablet</literal>,
-        <literal>handset</literal>,
-        <literal>watch</literal>, and
-        <literal>embedded</literal>,
-        as well as the special chassis types
-        <literal>vm</literal> and
-        <literal>container</literal> for
-        virtualized systems that lack an immediate physical chassis.</para>
-
-        <para>Note that most systems allow detection of the chassis type automatically (based on firmware
-        information or suchlike). This setting should only be used to override a misdetection or to manually
-        configure the chassis type where automatic detection is not available.</para>
-
-        <xi:include href="version-info.xml" xpointer="v197"/></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>DEPLOYMENT=</varname></term>
-
-        <listitem><para>Describes the system deployment environment.
-        One of the following is suggested:
-        <literal>development</literal>,
-        <literal>integration</literal>,
-        <literal>staging</literal>,
-        <literal>production</literal>.
-        </para>
-
-        <xi:include href="version-info.xml" xpointer="v216"/></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>LOCATION=</varname></term>
-
-        <listitem><para>Describes the system location if applicable
-        and known. Takes a human-friendly, free-form string. This may
-        be as generic as <literal>Berlin, Germany</literal> or as
-        specific as <literal>Left Rack, 2nd Shelf</literal>.
-        </para>
-
-        <xi:include href="version-info.xml" xpointer="v216"/></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>HARDWARE_VENDOR=</varname></term>
-
-        <listitem><para>Specifies the hardware vendor. If unspecified, the hardware vendor set in DMI or
-        <citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> will be
-        used.</para>
-
-        <xi:include href="version-info.xml" xpointer="v251"/></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>HARDWARE_MODEL=</varname></term>
-
-        <listitem><para>Specifies the hardware model. If unspecified, the hardware model set in DMI or
-        <citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> will be
-        used.</para>
-
-        <xi:include href="version-info.xml" xpointer="v251"/></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>HARDWARE_SKU=</varname></term>
-
-        <listitem><para>Specifies the hardware SKU (Stock-Keeping Unit). If unspecified, the hardware
-        SKU set in DMI will be used.</para>
-
-        <xi:include href="version-info.xml" xpointer="v258"/></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>HARDWARE_VERSION=</varname></term>
-
-        <listitem><para>Specifies the hardware version. If unspecified, the hardware version set in DMI
-        will be used.</para>
-
-        <xi:include href="version-info.xml" xpointer="v258"/></listitem>
-      </varlistentry>
-    </variablelist>
+    <refsect2>
+      <title>Machine Information</title>
+
+      <variablelist class='environment-variables'>
+
+        <varlistentry>
+          <term><varname>PRETTY_HOSTNAME=</varname></term>
+
+          <listitem><para>A pretty human-readable UTF-8 machine
+          identifier string. This should contain a name like
+          <literal>Lennart's Laptop</literal> which is useful to present
+          to the user and does not suffer by the syntax limitations of
+          internet domain names. If possible, the internet hostname as
+          configured in <filename>/etc/hostname</filename> should be
+          kept similar to this one. Example: if this value is
+          <literal>Lennart's Computer</literal> an Internet hostname of
+          <literal>lennarts-computer</literal> might be a good choice.
+          If this parameter is not set, an application should fall back
+          to the Internet hostname for presentation
+          purposes.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>ICON_NAME=</varname></term>
+
+          <listitem><para>An icon identifying this machine according to
+          the <ulink
+          url="https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
+          Icon Naming Specification</ulink>. If this parameter is not
+          set, an application should fall back to
+          <literal>computer</literal> or a similar icon
+          name.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>CHASSIS=</varname></term>
+
+          <listitem><para>The chassis type. Currently, the following
+          chassis types are defined:
+          <literal>desktop</literal>,
+          <literal>laptop</literal>,
+          <literal>convertible</literal>,
+          <literal>server</literal>,
+          <literal>tablet</literal>,
+          <literal>handset</literal>,
+          <literal>watch</literal>, and
+          <literal>embedded</literal>,
+          as well as the special chassis types
+          <literal>vm</literal> and
+          <literal>container</literal> for
+          virtualized systems that lack an immediate physical chassis.</para>
+
+          <para>Note that most systems allow detection of the chassis type automatically (based on firmware
+          information or suchlike). This setting should only be used to override a misdetection or to manually
+          configure the chassis type where automatic detection is not available.</para>
+
+          <xi:include href="version-info.xml" xpointer="v197"/></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>DEPLOYMENT=</varname></term>
+
+          <listitem><para>Describes the system deployment environment.
+          One of the following is suggested:
+          <literal>development</literal>,
+          <literal>integration</literal>,
+          <literal>staging</literal>,
+          <literal>production</literal>.
+          </para>
+
+          <xi:include href="version-info.xml" xpointer="v216"/></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>LOCATION=</varname></term>
+
+          <listitem><para>Describes the system location if applicable
+          and known. Takes a human-friendly, free-form string. This may
+          be as generic as <literal>Berlin, Germany</literal> or as
+          specific as <literal>Left Rack, 2nd Shelf</literal>.
+          </para>
+
+          <xi:include href="version-info.xml" xpointer="v216"/></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>HARDWARE_VENDOR=</varname></term>
+
+          <listitem><para>Specifies the hardware vendor. If unspecified, the hardware vendor set in DMI or
+          <citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> will be
+          used.</para>
+
+          <xi:include href="version-info.xml" xpointer="v251"/></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>HARDWARE_MODEL=</varname></term>
+
+          <listitem><para>Specifies the hardware model. If unspecified, the hardware model set in DMI or
+          <citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> will be
+          used.</para>
+
+          <xi:include href="version-info.xml" xpointer="v251"/></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>HARDWARE_SKU=</varname></term>
+
+          <listitem><para>Specifies the hardware SKU (Stock-Keeping Unit). If unspecified, the hardware
+          SKU set in DMI will be used.</para>
+
+          <xi:include href="version-info.xml" xpointer="v258"/></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>HARDWARE_VERSION=</varname></term>
+
+          <listitem><para>Specifies the hardware version. If unspecified, the hardware version set in DMI
+          will be used.</para>
+
+          <xi:include href="version-info.xml" xpointer="v258"/></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+    <refsect2>
+      <title>Custom Fields</title>
+
+      <para>Operating system vendors and systemd administrators 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.</para>
+
+      <para>Example: <literal>_LOCAL_EMERGENCY_CONTACT="user@example.org"</literal>.</para>
+    </refsect2>
   </refsect1>
 
   <refsect1>

diff --git a/tools/command_ignorelist b/tools/command_ignorelist
index aed479938f64ec6102ff6cf2293e466f879bd226..2cdaf4de7f72822846651a9564dc74cae94ca346 100644 (file)
--- a/tools/command_ignorelist
+++ b/tools/command_ignorelist
@@ -49,8 +49,8 @@ logind.conf.xml ./refsect1[title="Options"]/variablelist/varlistentry[term="NAut
 logind.conf.xml ./refsect1[title="Options"]/variablelist/varlistentry[term="KillUserProcesses="]
 logind.conf.xml ./refsect1[title="Options"]/variablelist/varlistentry[term="KillOnlyUsers="]
 logind.conf.xml ./refsect1[title="Options"]/variablelist/varlistentry[term="InhibitDelayMaxSec="]
-machine-info.xml ./refsect1[title="Options"]/variablelist/varlistentry[term="PRETTY_HOSTNAME="]
-machine-info.xml ./refsect1[title="Options"]/variablelist/varlistentry[term="ICON_NAME="]
+machine-info.xml ./refsect1[title="Options"]/refsect2[title="Machine Information"]/variablelist/varlistentry[term="PRETTY_HOSTNAME="]
+machine-info.xml ./refsect1[title="Options"]/refsect2[title="Machine Information"]/variablelist/varlistentry[term="ICON_NAME="]
 os-release.xml ./refsect1[title="Options"]/refsect2[title="General information identifying the operating system"]/variablelist/varlistentry[term="NAME="]
 os-release.xml ./refsect1[title="Options"]/refsect2[title="Information about the version of the operating system"]/variablelist/varlistentry[term="VERSION="]
 os-release.xml ./refsect1[title="Options"]/refsect2[title="General information identifying the operating system"]/variablelist/varlistentry[term="ID="]