man: document new specifiers

5 files changed, 69 insertions, 8 deletions

diff --git a/man/standard-specifiers.xml b/man/standard-specifiers.xml
new file mode 100644
index 0000000000..c5cd6a8862
--- /dev/null
+++ b/man/standard-specifiers.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<tbody>
+  <row id='a'>
+    <entry><literal>%a</literal></entry>
+    <entry>Architecture</entry>
+    <entry>A short string identifying the architecture of the local system. A string such as <constant>x86</constant>, <constant>x86-64</constant> or <constant>arm64</constant>. See the architectures defined for <varname>ConditionArchitecture=</varname> in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a full list.</entry>
+  </row>
+  <row id='B'>
+    <entry><literal>%B</literal></entry>
+    <entry>Operating system build ID</entry>
+    <entry>The operating system build identifier of the running system, as read from the <varname>BUILD_ID=</varname> field of <filename>/etc/os-release</filename>. If not set, resolves to an empty string. See <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+  </row>
+  <row id='o'>
+    <entry><literal>%o</literal></entry>
+    <entry>Operating system ID</entry>
+    <entry>The operating system identifier of the running system, as read from the <varname>ID=</varname> field of <filename>/etc/os-release</filename>. See <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+  </row>
+  <row id='w'>
+    <entry><literal>%w</literal></entry>
+    <entry>Operating system version ID</entry>
+    <entry>The operating system version identifier of the running system, as read from the <varname>VERSION_ID=</varname> field of <filename>/etc/os-release</filename>. If not set, resolves to an empty string. See <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+  </row>
+  <row id='W'>
+    <entry><literal>%W</literal></entry>
+    <entry>Operating system variant ID</entry>
+    <entry>The operating system variant identifier of the running system, as read from the <varname>VARIANT_ID=</varname> field of <filename>/etc/os-release</filename>. If not set, resolves to an empty string. See <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+  </row>
+</tbody>
diff --git a/man/systemd.dnssd.xml b/man/systemd.dnssd.xml
index 1ac760eec7..d70cc43944 100644
--- a/man/systemd.dnssd.xml
+++ b/man/systemd.dnssd.xml
@@ -3,7 +3,9 @@
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
 
-<refentry id="systemd.dnssd" conditional='ENABLE_RESOLVE'>
+<refentry id="systemd.dnssd"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          conditional='ENABLE_RESOLVE'>
 
   <refentryinfo>
     <title>systemd.dnssd</title>
@@ -87,26 +89,31 @@
                   </row>
                 </thead>
                 <tbody>
-                  <row>
-                    <entry><literal>%m</literal></entry>
-                    <entry>Machine ID</entry>
-                    <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
-                  </row>
+                  <xi:include href="standard-specifiers.xml" xpointer="a"/>
                   <row>
                     <entry><literal>%b</literal></entry>
                     <entry>Boot ID</entry>
                     <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
                   </row>
+                  <xi:include href="standard-specifiers.xml" xpointer="B"/>
                   <row>
                     <entry><literal>%H</literal></entry>
                     <entry>Host name</entry>
                     <entry>The hostname of the running system.</entry>
                   </row>
                   <row>
+                    <entry><literal>%m</literal></entry>
+                    <entry>Machine ID</entry>
+                    <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+                  </row>
+                  <xi:include href="standard-specifiers.xml" xpointer="o"/>
+                  <row>
                     <entry><literal>%v</literal></entry>
                     <entry>Kernel release</entry>
                     <entry>Identical to <command>uname -r</command> output.</entry>
                   </row>
+                  <xi:include href="standard-specifiers.xml" xpointer="w"/>
+                  <xi:include href="standard-specifiers.xml" xpointer="W"/>
                 </tbody>
               </tgroup>
             </table>
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index c26937e752..d570016b2f 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -6,7 +6,8 @@
 ]>
 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
 
-<refentry id="systemd.unit">
+<refentry id="systemd.unit"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>systemd.unit</title>
@@ -1709,10 +1710,17 @@
         </thead>
         <tbody>
           <row>
+            <!-- We do not use the common definition from standard-specifiers.xml here since it includes a reference onto our own man page, which would make the rendered version self-referential. -->
+            <entry><literal>%a</literal></entry>
+            <entry>Architecture</entry>
+            <entry>A short string identifying the architecture of the local system. A string such as <constant>x86</constant>, <constant>x86-64</constant> or <constant>arm64</constant>. See the architectures defined for <varname>ConditionArchitecture=</varname> above for a full list.</entry>
+          </row>
+          <row>
             <entry><literal>%b</literal></entry>
             <entry>Boot ID</entry>
             <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
           </row>
+          <xi:include href="standard-specifiers.xml" xpointer="B"/>
           <row>
             <entry><literal>%C</literal></entry>
             <entry>Cache directory root</entry>
@@ -1770,6 +1778,7 @@ Note that this setting is <emphasis>not</emphasis> influenced by the <varname>Us
             <entry>Machine ID</entry>
             <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
           </row>
+          <xi:include href="standard-specifiers.xml" xpointer="o"/>
           <row>
             <entry><literal>%n</literal></entry>
             <entry>Full unit name</entry>
@@ -1844,6 +1853,8 @@ Note that this setting is <emphasis>not</emphasis> influenced by the <varname>Us
             <entry>Directory for larger and persistent temporary files</entry>
             <entry>This is either <filename>/var/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry>
           </row>
+          <xi:include href="standard-specifiers.xml" xpointer="w"/>
+          <xi:include href="standard-specifiers.xml" xpointer="W"/>
           <row>
             <entry><literal>%%</literal></entry>
             <entry>Single percent sign</entry>
diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml
index f0e0f2bedc..2be41c1030 100644
--- a/man/sysusers.d.xml
+++ b/man/sysusers.d.xml
@@ -251,11 +251,13 @@ r     -        500-900
             </row>
           </thead>
           <tbody>
+            <xi:include href="standard-specifiers.xml" xpointer="a"/>
             <row>
               <entry><literal>%b</literal></entry>
               <entry>Boot ID</entry>
               <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
             </row>
+            <xi:include href="standard-specifiers.xml" xpointer="B"/>
             <row>
               <entry><literal>%H</literal></entry>
               <entry>Host name</entry>
@@ -266,6 +268,7 @@ r     -        500-900
               <entry>Machine ID</entry>
               <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
             </row>
+            <xi:include href="standard-specifiers.xml" xpointer="o"/>
             <row>
               <entry><literal>%T</literal></entry>
               <entry>Directory for temporary files</entry>
@@ -281,6 +284,8 @@ r     -        500-900
               <entry>Directory for larger and persistent temporary files</entry>
               <entry>This is either <filename>/var/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry>
             </row>
+            <xi:include href="standard-specifiers.xml" xpointer="w"/>
+            <xi:include href="standard-specifiers.xml" xpointer="W"/>
             <row>
               <entry><literal>%%</literal></entry>
               <entry>Escaped <literal>%</literal></entry>
diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml
index a29c913ff0..79fd6a9921 100644
--- a/man/tmpfiles.d.xml
+++ b/man/tmpfiles.d.xml
@@ -6,7 +6,8 @@
 
   Copyright © 2010 Brandon Philips
 -->
-<refentry id="tmpfiles.d">
+<refentry id="tmpfiles.d"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>tmpfiles.d</title>
@@ -631,11 +632,13 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
             </row>
           </thead>
           <tbody>
+            <xi:include href="standard-specifiers.xml" xpointer="a"/>
             <row>
               <entry><literal>%b</literal></entry>
               <entry>Boot ID</entry>
               <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
             </row>
+            <xi:include href="standard-specifiers.xml" xpointer="B"/>
             <row>
               <entry><literal>%C</literal></entry>
               <entry>System or user cache directory</entry>
@@ -661,6 +664,7 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
               <entry>Machine ID</entry>
               <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
             </row>
+            <xi:include href="standard-specifiers.xml" xpointer="o"/>
             <row>
               <entry><literal>%S</literal></entry>
               <entry>System or user state directory</entry>
@@ -706,6 +710,8 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
               <entry>Directory for larger and persistent temporary files</entry>
               <entry>This is either <filename>/var/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry>
             </row>
+            <xi:include href="standard-specifiers.xml" xpointer="w"/>
+            <xi:include href="standard-specifiers.xml" xpointer="W"/>
             <row>
               <entry><literal>%%</literal></entry>
               <entry>Escaped <literal>%</literal></entry>