From 09a89190bb40c7c7fa740c4d0997f3bd5c88de8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Behrmann?= Date: Wed, 20 Aug 2025 13:56:00 +0200 Subject: [PATCH 1/3] man: add note about extending machine-info to man page --- man/machine-info.xml | 201 +++++++++++++++++++++------------------ tools/command_ignorelist | 4 +- 2 files changed, 109 insertions(+), 96 deletions(-) diff --git a/man/machine-info.xml b/man/machine-info.xml index c766db2708..cd254a9c35 100644 --- a/man/machine-info.xml +++ b/man/machine-info.xml @@ -53,126 +53,139 @@ The following machine metadata parameters may be set using /etc/machine-info: - + + Machine Information - - PRETTY_HOSTNAME= + - A pretty human-readable UTF-8 machine - identifier string. This should contain a name like - Lennart's Laptop 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 /etc/hostname should be - kept similar to this one. Example: if this value is - Lennart's Computer an Internet hostname of - lennarts-computer might be a good choice. - If this parameter is not set, an application should fall back - to the Internet hostname for presentation - purposes. - + + PRETTY_HOSTNAME= - - ICON_NAME= + A pretty human-readable UTF-8 machine + identifier string. This should contain a name like + Lennart's Laptop 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 /etc/hostname should be + kept similar to this one. Example: if this value is + Lennart's Computer an Internet hostname of + lennarts-computer might be a good choice. + If this parameter is not set, an application should fall back + to the Internet hostname for presentation + purposes. + - An icon identifying this machine according to - the XDG - Icon Naming Specification. If this parameter is not - set, an application should fall back to - computer or a similar icon - name. - + + ICON_NAME= - - CHASSIS= + An icon identifying this machine according to + the XDG + Icon Naming Specification. If this parameter is not + set, an application should fall back to + computer or a similar icon + name. + - The chassis type. Currently, the following - chassis types are defined: - desktop, - laptop, - convertible, - server, - tablet, - handset, - watch, and - embedded, - as well as the special chassis types - vm and - container for - virtualized systems that lack an immediate physical chassis. + + CHASSIS= - 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. + The chassis type. Currently, the following + chassis types are defined: + desktop, + laptop, + convertible, + server, + tablet, + handset, + watch, and + embedded, + as well as the special chassis types + vm and + container for + virtualized systems that lack an immediate physical chassis. - - + 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. - - DEPLOYMENT= + + - Describes the system deployment environment. - One of the following is suggested: - development, - integration, - staging, - production. - + + DEPLOYMENT= - - + Describes the system deployment environment. + One of the following is suggested: + development, + integration, + staging, + production. + - - LOCATION= + + - Describes the system location if applicable - and known. Takes a human-friendly, free-form string. This may - be as generic as Berlin, Germany or as - specific as Left Rack, 2nd Shelf. - + + LOCATION= - - + Describes the system location if applicable + and known. Takes a human-friendly, free-form string. This may + be as generic as Berlin, Germany or as + specific as Left Rack, 2nd Shelf. + - - HARDWARE_VENDOR= + + - Specifies the hardware vendor. If unspecified, the hardware vendor set in DMI or - hwdb7 will be - used. + + HARDWARE_VENDOR= - - + Specifies the hardware vendor. If unspecified, the hardware vendor set in DMI or + hwdb7 will be + used. - - HARDWARE_MODEL= + + - Specifies the hardware model. If unspecified, the hardware model set in DMI or - hwdb7 will be - used. + + HARDWARE_MODEL= - - + Specifies the hardware model. If unspecified, the hardware model set in DMI or + hwdb7 will be + used. - - HARDWARE_SKU= + + - Specifies the hardware SKU (Stock-Keeping Unit). If unspecified, the hardware - SKU set in DMI will be used. + + HARDWARE_SKU= - - + Specifies the hardware SKU (Stock-Keeping Unit). If unspecified, the hardware + SKU set in DMI will be used. - - HARDWARE_VERSION= + + - Specifies the hardware version. If unspecified, the hardware version set in DMI - will be used. + + HARDWARE_VERSION= - - - + Specifies the hardware version. If unspecified, the hardware version set in DMI + will be used. + + + + + + + Custom Fields + + 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. + + Example: _LOCAL_EMERGENCY_CONTACT="user@example.org". + diff --git a/tools/command_ignorelist b/tools/command_ignorelist index aed479938f..2cdaf4de7f 100644 --- 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="] From 1dcbb0b4ca48fe69e2984943d536c3f4252b12b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Behrmann?= Date: Wed, 20 Aug 2025 15:47:28 +0200 Subject: [PATCH 2/3] tools: ignore root element explicitly in check-version-history Currently these messages (broken for length) 2025-08-20T12:04:15.9609277Z /home/runner/work/systemd/systemd/tools/check-version-history.py:26: FutureWarning: This search incorrectly ignores the root element, and will be fixed in a future version. If you rely on the current behaviour, change it to './/funcprototype/funcdef/function' can be seen in CI output. So let's apply the suggestion. --- tools/check-version-history.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/check-version-history.py b/tools/check-version-history.py index dce2b6abd1..db32b6920a 100755 --- a/tools/check-version-history.py +++ b/tools/check-version-history.py @@ -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] From 717500702060c80664c23c74bdc42675c0806fd9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Behrmann?= Date: Mon, 25 Aug 2025 14:37:15 +0200 Subject: [PATCH 3/3] man: unify spelling of OS-specific --- man/os-release.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/os-release.xml b/man/os-release.xml index aa1ef03a40..4bbb87b1bf 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -642,7 +642,7 @@ set. 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. Example: DEBIAN_BTS="debbugs://bugs.debian.org/".