man: add note about extending machine-info to man page (#38652)
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
+107
-94
@@ -53,126 +53,139 @@
|
||||
<para>The following machine metadata parameters may be set using
|
||||
<filename>/etc/machine-info</filename>:</para>
|
||||
|
||||
<variablelist class='environment-variables'>
|
||||
<refsect2>
|
||||
<title>Machine Information</title>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>PRETTY_HOSTNAME=</varname></term>
|
||||
<variablelist class='environment-variables'>
|
||||
|
||||
<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>PRETTY_HOSTNAME=</varname></term>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ICON_NAME=</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>
|
||||
|
||||
<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>ICON_NAME=</varname></term>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>CHASSIS=</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>
|
||||
|
||||
<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>
|
||||
<varlistentry>
|
||||
<term><varname>CHASSIS=</varname></term>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v197"/></listitem>
|
||||
</varlistentry>
|
||||
<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>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>DEPLOYMENT=</varname></term>
|
||||
<xi:include href="version-info.xml" xpointer="v197"/></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<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>
|
||||
<varlistentry>
|
||||
<term><varname>DEPLOYMENT=</varname></term>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v216"/></listitem>
|
||||
</varlistentry>
|
||||
<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>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>LOCATION=</varname></term>
|
||||
<xi:include href="version-info.xml" xpointer="v216"/></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<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>
|
||||
<varlistentry>
|
||||
<term><varname>LOCATION=</varname></term>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v216"/></listitem>
|
||||
</varlistentry>
|
||||
<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>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>HARDWARE_VENDOR=</varname></term>
|
||||
<xi:include href="version-info.xml" xpointer="v216"/></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<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>
|
||||
<varlistentry>
|
||||
<term><varname>HARDWARE_VENDOR=</varname></term>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
|
||||
</varlistentry>
|
||||
<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>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>HARDWARE_MODEL=</varname></term>
|
||||
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<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>
|
||||
<varlistentry>
|
||||
<term><varname>HARDWARE_MODEL=</varname></term>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
|
||||
</varlistentry>
|
||||
<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>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>HARDWARE_SKU=</varname></term>
|
||||
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<listitem><para>Specifies the hardware SKU (Stock-Keeping Unit). If unspecified, the hardware
|
||||
SKU set in DMI will be used.</para>
|
||||
<varlistentry>
|
||||
<term><varname>HARDWARE_SKU=</varname></term>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
|
||||
</varlistentry>
|
||||
<listitem><para>Specifies the hardware SKU (Stock-Keeping Unit). If unspecified, the hardware
|
||||
SKU set in DMI will be used.</para>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>HARDWARE_VERSION=</varname></term>
|
||||
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<listitem><para>Specifies the hardware version. If unspecified, the hardware version set in DMI
|
||||
will be used.</para>
|
||||
<varlistentry>
|
||||
<term><varname>HARDWARE_VERSION=</varname></term>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<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>
|
||||
|
||||
+1
-1
@@ -642,7 +642,7 @@
|
||||
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
|
||||
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>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal>.</para>
|
||||
|
||||
@@ -23,7 +23,7 @@ def find_undocumented_functions(pages, ignorelist):
|
||||
assert pagetree.getroot().tag == "refentry"
|
||||
|
||||
hist_section = pagetree.find("refsect1[title='History']")
|
||||
for func in pagetree.findall("//funcprototype/funcdef/function"):
|
||||
for func in pagetree.findall(".//funcprototype/funcdef/function"):
|
||||
path = f"./refsynopsisdiv/funcsynopsis/funcprototype/funcdef/function[.='{func.text}']"
|
||||
assert pagetree.findall(path) == [func]
|
||||
|
||||
|
||||
@@ -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="]
|
||||
|
||||
Reference in New Issue
Block a user