Merge pull request #16170 from keszybz/man-user@

Better documentation for user@ services

man/directives-template.xml

@@ -1,6 +1,6 @@
 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
 
-<refentry id="systemd.directives" conditional="HAVE_PYTHON">
+<refentry id="systemd.directives">
   <refentryinfo>
     <title>systemd.directives</title>
     <productname>systemd</productname>

man/rules/meson.build

@@ -18,7 +18,7 @@ manpages = [
  ['file-hierarchy', '7', [], ''],
  ['halt', '8', ['poweroff', 'reboot'], ''],
  ['homectl', '1', [], 'ENABLE_HOMED'],
- ['homed.conf', '5', ['homed.conf.d'], 'ENABLE_RESOLVE'],
+ ['homed.conf', '5', ['homed.conf.d'], 'ENABLE_HOMED'],
  ['hostname', '5', [], ''],
  ['hostnamectl', '1', [], 'ENABLE_HOSTNAMED'],
  ['hwdb', '7', [], 'ENABLE_HWDB'],
@@ -1096,7 +1096,10 @@ manpages = [
   ''],
  ['udev_new', '3', ['udev_ref', 'udev_unref'], ''],
  ['udevadm', '8', [], ''],
- ['user@.service', '5', ['user-runtime-dir@.service'], ''],
+ ['user@.service',
+  '5',
+  ['systemd-user-runtime-dir', 'user-runtime-dir@.service'],
+  ''],
  ['userdbctl', '1', [], 'ENABLE_USERDB'],
  ['vconsole.conf', '5', [], 'ENABLE_VCONSOLE']
 ]

man/user@.service.xml

@@ -17,34 +17,37 @@
   <refnamediv>
     <refname>user@.service</refname>
     <refname>user-runtime-dir@.service</refname>
-    <refpurpose>System units to manage user processes</refpurpose>
+    <refname>systemd-user-runtime-dir</refname>
+    <refpurpose>System units to start the user manager</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
     <para><filename>user@<replaceable>UID</replaceable>.service</filename></para>
     <para><filename>user-runtime-dir@<replaceable>UID</replaceable>.service</filename></para>
+    <para><filename>/usr/lib/systemd/systemd-user-runtime-dir</filename></para>
     <para><filename>user-<replaceable>UID</replaceable>.slice</filename></para>
   </refsynopsisdiv>
 
   <refsect1>
     <title>Description</title>
 
-    <para>The
-    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    <para>The <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     system manager (PID 1) starts user manager instances as
-    <filename>user@<replaceable>UID</replaceable>.service</filename>, where the user's numerical UID
-    is used as the instance identifier. Each <command>systemd --user</command> instance manages a
-    hierarchy of its own units. See
-    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
-    a discussion of systemd units and
-    <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    for a list of units that form the basis of the unit hierarchies of system and user units.</para>
+    <filename>user@<replaceable>UID</replaceable>.service</filename>, with the user's numerical UID used as
+    the instance identifier. These instances use the same executable as the system manager, but running in a
+    mode where it starts a different set of units. Each <command>systemd --user</command> instance manages a
+    hierarchy of units specific to that user. See
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> for a
+    discussion of units and
+    <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>1</manvolnum></citerefentry> for a
+    list of units that form the basis of the unit hierarchies of system and user units.</para>
 
     <para><filename>user@<replaceable>UID</replaceable>.service</filename> is accompanied by the
     system unit <filename>user-runtime-dir@<replaceable>UID</replaceable>.service</filename>, which
     creates the user's runtime directory
     <filename>/run/user/<replaceable>UID</replaceable></filename>, and then removes it when this
-    unit is stopped.</para>
+    unit is stopped. <filename>user-runtime-dir@<replaceable>UID</replaceable>.service</filename>
+    executes the <filename>systemd-user-runtime-dir</filename> binary to do the actual work.</para>
 
     <para>User processes may be started by the <filename>user@.service</filename> instance, in which
     case they will be part of that unit in the system hierarchy. They may also be started elsewhere,
@@ -53,7 +56,7 @@
     display manager like <command>gdm</command>, in which case they form a .scope unit (see
     <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
     Both <filename>user@<replaceable>UID</replaceable>.service</filename> and the scope units are
-    collected under a <filename>user-<replaceable>UID</replaceable>.slice</filename>.</para>
+    collected under the <filename>user-<replaceable>UID</replaceable>.slice</filename>.</para>
 
     <para>Individual <filename>user-<replaceable>UID</replaceable>.slice</filename> slices are
     collected under <filename>user.slice</filename>, see

tools/make-man-index.py

@@ -9,7 +9,7 @@ from xml_helper import xml_parse, xml_print, tree
 MDASH = ' — ' if sys.version_info.major >= 3 else ' -- '
 
 TEMPLATE = '''\
-<refentry id="systemd.index" conditional="HAVE_PYTHON">
+<refentry id="systemd.index">
 
   <refentryinfo>
     <title>systemd.index</title>

tools/update-man-rules.py

@@ -4,16 +4,13 @@
 from __future__ import print_function
 import collections
 import sys
-import os.path
 import pprint
+from os.path import basename
 from xml_helper import xml_parse
 
 def man(page, number):
     return '{}.{}'.format(page, number)
 
-def xml(file):
-    return os.path.basename(file)
-
 def add_rules(rules, name):
     xml = xml_parse(name)
     # print('parsing {}'.format(name), file=sys.stderr)
@@ -78,9 +75,12 @@ def make_mesonfile(rules, dist_files):
 
 if __name__ == '__main__':
     pages = sys.argv[1:]
+    pages = (p for p in pages
+             if basename(p) not in {
+                     'systemd.directives.xml',
+                     'systemd.index.xml',
+                     'directives-template.xml'})
 
     rules = create_rules(pages)
-    dist_files = (xml(file) for file in pages
-                  if not file.endswith(".directives.xml") and
-                     not file.endswith(".index.xml"))
+    dist_files = (basename(p) for p in pages)
     print(make_mesonfile(rules, dist_files))