Merge pull request #23057 from keszybz/various-doc-tweaks

Various doc tweaks

README

@@ -207,7 +207,7 @@ REQUIREMENTS:
         python-jinja2
         python-lxml (optional, required to build the indices)
         python >= 3.5
-        meson >= 0.53.2 (>= 0.54.0 is required to build with 'meson compile')
+        meson >= 0.53.2
         ninja
         gcc, awk, sed, grep, and similar tools
         clang >= 10.0, llvm >= 10.0 (optional, required to build BPF programs
@@ -225,7 +225,7 @@ REQUIREMENTS:
         polkit (optional)
 
         To build in directory build/:
-          meson setup build/ && meson compile -C build/
+          meson setup build/ && ninja -C build/
 
         Any configuration options can be specified as -Darg=value... arguments
         to meson. After the build directory is initially configured, meson will
@@ -235,13 +235,13 @@ REQUIREMENTS:
         their current values.
 
         Useful commands:
-          meson compile -v -C build/ some/target
+          ninja -C build -v some/target
           meson test -C build/
           sudo meson install -C build/
           DESTDIR=... meson install -C build/
 
         A tarball can be created with:
-          git archive --format=tar --prefix=systemd-222/ v222 | xz > systemd-222.tar.xz
+          v=250 && git archive --prefix=systemd-$v/ v$v | zstd >systemd-$v.tar.zstd
 
         When systemd-hostnamed is used, it is strongly recommended to
         install nss-myhostname to ensure that, in a world of

docs/CODE_QUALITY.md

@@ -38,18 +38,19 @@ available functionality:
    `./tools/find-tabs.sh recpatch` to fix them. (Again, grain of salt, foreign
    headers should usually be left unmodified.)
 
-6. Use `meson compile -C build check-api-docs` to compare the list of exported
+6. Use `ninja -C build check-api-docs` to compare the list of exported symbols
-   symbols of `libsystemd.so` and `libudev.so` with the list of man pages. Symbols
+   of `libsystemd.so` and `libudev.so` with the list of man pages. Symbols
    lacking documentation are highlighted.
 
-7. Use `meson compile -C build update-hwdb` to automatically download and import the
+7. Use `ninja -C build update-hwdb` and `ninja -C build update-hwdb-autosuspend`
-   PCI, USB and OUI databases into hwdb.
+   to automatically download and import the PCI, USB, and OUI databases and the
+   autosuspend quirks into the hwdb.
 
-8. Use `meson compile -C build update-man-rules` to update the meson rules for
+8. Use `ninja -C build update-man-rules` to update the meson rules for building
-   building man pages automatically from the docbook XML files included in
+   man pages automatically from the docbook XML files included in `man/`.
-   `man/`.
 
-9. There are multiple CI systems in use that run on every github PR submission.
+9. There are multiple CI systems in use that run on every github pull request
+   submission or update.
 
 10. [Coverity](https://scan.coverity.com/) is analyzing systemd `main` branch
     in regular intervals. The reports are available

docs/HACKING.md

@@ -98,7 +98,7 @@ $ cd systemd
 $ git checkout -b <BRANCH>        # where BRANCH is the name of the branch
 $ vim src/core/main.c             # or wherever you'd like to make your changes
 $ meson build                     # configure the build
-$ meson compile -C build                  # build it locally, see if everything compiles fine
+$ ninja -C build                  # build it locally, see if everything compiles fine
 $ meson test -C build             # run some simple regression tests
 $ sudo mkosi                      # build a test image
 $ sudo mkosi boot                 # boot up the test image

docs/RELEASE.md

@@ -8,17 +8,18 @@ SPDX-License-Identifier: LGPL-2.1-or-later
 # Steps to a Successful Release
 
 1. Add all items to NEWS
-2. Update the contributors list in NEWS (`meson compile -C build git-contrib`)
+2. Update the contributors list in NEWS (`ninja -C build git-contrib`)
 3. Update the time and place in NEWS
-4. Update hwdb (`meson compile -C build update-hwdb update-hwdb-autosuspend`)
+4. Update hwdb (`ninja -C build update-hwdb`, `ninja -C build update-hwdb-autosuspend`, commit separately).
-5. [RC1] Update version and library numbers in `meson.build`
+5. Update syscall numbers (`ninja -C build update-syscall-tables update-syscall-headers`).
-6. Check dbus docs with `meson compile -C build update-dbus-docs`
+6. [RC1] Update version and library numbers in `meson.build`
-7. Tag the release: `version=vXXX-rcY && git tag -s "${version}" -m "systemd ${version}"`
+7. Check dbus docs with `ninja -C build update-dbus-docs`
-8. Do `meson compile -C build`
+8. Tag the release: `version=vXXX-rcY && git tag -s "${version}" -m "systemd ${version}"`
-9. Make sure that the version string and package string match: `build/systemctl --version`
+9. Do `ninja -C build`
-10. Upload the documentation: `meson compile -C build doc-sync`
+10. Make sure that the version string and package string match: `build/systemctl --version`
-11. [FINAL] Close the github milestone and open a new one (https://github.com/systemd/systemd/milestones)
+11. Upload the documentation: `ninja -C build doc-sync`
-12. "Draft" a new release on github (https://github.com/systemd/systemd/releases/new), mark "This is a pre-release" if appropriate.
+12. [FINAL] Close the github milestone and open a new one (https://github.com/systemd/systemd/milestones)
-13. Check that announcement to systemd-devel, with a copy&paste from NEWS, was sent. This should happen automatically.
+13. "Draft" a new release on github (https://github.com/systemd/systemd/releases/new), mark "This is a pre-release" if appropriate.
-14. Update IRC topic (`/msg chanserv TOPIC #systemd Version NNN released`)
+14. Check that announcement to systemd-devel, with a copy&paste from NEWS, was sent. This should happen automatically.
-15. [FINAL] Push commits to stable, create an empty -stable branch: `git push systemd-stable --atomic origin/main:main origin/main:refs/heads/${version}-stable`, and change the default branch to latest release (https://github.com/systemd/systemd-stable/settings/branches).
+15. Update IRC topic (`/msg chanserv TOPIC #systemd Version NNN released`)
+16. [FINAL] Push commits to stable, create an empty -stable branch: `git push systemd-stable --atomic origin/main:main origin/main:refs/heads/${version}-stable`, and change the default branch to latest release (https://github.com/systemd/systemd-stable/settings/branches).

docs/TRANSLATORS.md

@@ -27,7 +27,7 @@ To create a translation to a language not yet available, start by creating the
 initial template:
 
 ```
-$ meson compile -C build/ systemd-pot
+$ ninja -C build/ systemd-pot
 ```
 
 This will generate file `po/systemd.pot` in the source tree.
@@ -51,7 +51,7 @@ using the `poedit` GUI editor.)
 Start by updating the `*.po` files from the latest template:
 
 ```
-$ meson compile -C build/ systemd-update-po
+$ ninja -C build/ systemd-update-po
 ```
 
 This will touch all the `*.po` files, so you'll want to pay attention when
@@ -75,7 +75,7 @@ using `git checkout -- po/` after you commit the changes you do want to keep.)
 You can recompile the `*.po` files using the following command:
 
 ```
-$ meson compile -C build/ systemd-gmo
+$ ninja -C build/ systemd-gmo
 ```
 
 The resulting files will be saved in the `build/po/` directory.

man/libudev.xml

@@ -37,8 +37,10 @@
   <refsect1>
     <title>Description</title>
 
-    <para><filename>libudev.h</filename> provides APIs to introspect
+    <para><filename>libudev.h</filename> provides an API to introspect and enumerate devices on the local
-    and enumerate devices on the local system.</para>
+    system. This library is supported, but should not be used in new projects. Please see
+    <citerefentry><refentrytitle>sd-device</refentrytitle><manvolnum>3</manvolnum></citerefentry> for an
+    equivalent replacement with a more modern API.</para>
 
     <para>All functions require a libudev context to operate. This
     context can be create via

man/os-release.xml

@@ -117,7 +117,7 @@
       change between the build and the deployment phases, it is possible to relax this check: if exactly one
       file whose name matches <literal><filename>extension-release.*</filename></literal> is present in this
       directory, and the file is tagged with a <varname>user.extension-release.strict</varname>
-      <citerefentry><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry> set to the
+      <citerefentry project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry> set to the
       string <literal>0</literal>, it will be used instead.</para>
 
       <para>The rest of this document that talks about <filename>os-release</filename> should be understood
@@ -499,14 +499,14 @@ VERSION_ID=32</programlisting>
 
     <example>
       <title>Reading <filename>os-release</filename> in
-      <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
+      <citerefentry project='man-pages'><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
 
       <programlisting><xi:include href="check-os-release.sh" parse="text" /></programlisting>
     </example>
 
     <example>
       <title>Reading <filename>os-release</filename> in
-      <citerefentry><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (versions &gt;= 3.10)</title>
+      <citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (versions &gt;= 3.10)</title>
 
       <programlisting><xi:include href="check-os-release-simple.py" parse="text" /></programlisting>
 
@@ -517,7 +517,7 @@ VERSION_ID=32</programlisting>
 
     <example>
       <title>Reading <filename>os-release</filename> in
-      <citerefentry><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (any version)</title>
+      <citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (any version)</title>
 
       <programlisting><xi:include href="check-os-release.py" parse="text" /></programlisting>
 

man/rules/meson.build

@@ -117,6 +117,7 @@ manpages = [
    'SD_NOTICE',
    'SD_WARNING'],
   ''],
+ ['sd-device', '3', [], ''],
  ['sd-event', '3', [], ''],
  ['sd-hwdb', '3', [], ''],
  ['sd-id128',
@@ -515,6 +516,7 @@ manpages = [
    'sd_device_get_sysname',
    'sd_device_get_sysnum'],
   ''],
+ ['sd_device_ref', '3', ['sd_device_unref', 'sd_device_unrefp'], ''],
  ['sd_event_add_child',
   '3',
   ['sd_event_add_child_pidfd',

man/sd-device.xml

@@ -0,0 +1,62 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="sd-device" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd-device</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd-device</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd-device</refname>
+    <refpurpose>API for enumerating and introspecting local devices</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-device.h&gt;</funcsynopsisinfo>
+    </funcsynopsis>
+
+    <cmdsynopsis>
+      <command>pkg-config --cflags --libs libsystemd</command>
+    </cmdsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><filename>sd-device.h</filename> provides an API to introspect and enumerate devices on the local
+    system. It provides a programmatic interface to the database of devices and their properties mananaged by
+    <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+    This API is a replacement for
+    <citerefentry><refentrytitle>libudev</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
+    <filename>libudev.h</filename>.</para>
+
+    <para>See
+    <literallayout><citerefentry><refentrytitle>sd_device_get_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_device_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+</literallayout>
+    for more information about the functions available.</para>
+  </refsect1>
+
+  <xi:include href="libsystemd-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>

man/sd_bus_message_new.xml

@@ -99,14 +99,13 @@
     <citerefentry><refentrytitle>sd_bus_message_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
     </para>
 
-    <para><function>sd_bus_message_ref()</function> increases the reference counter of
+    <para><function>sd_bus_message_ref()</function> increases the internal reference counter of
     <parameter>m</parameter> by one.</para>
 
-    <para><function>sd_bus_message_unref()</function> decreases the reference counter of
+    <para><function>sd_bus_message_unref()</function> decreases the internal reference counter of
     <parameter>m</parameter> by one. Once the reference count has dropped to zero, message object is
-    destroyed and cannot be used anymore, so further calls to
+    destroyed and cannot be used anymore, so further calls to <function>sd_bus_message_ref()</function> or
-    <function>sd_bus_message_ref()</function> or <function>sd_bus_message_unref()</function> are
+    <function>sd_bus_message_unref()</function> are illegal.</para>
-    illegal.</para>
 
     <para><function>sd_bus_message_unrefp()</function> is similar to
     <function>sd_bus_message_unref()</function> but takes a pointer to a

man/sd_bus_new.xml

@@ -109,7 +109,7 @@
     pointer to an <type>sd_bus</type> object. This call is useful in
     conjunction with GCC's and LLVM's <ulink
     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
-    Variable Attribute</ulink>. Note that this function is defined as
+    Variable Attribute</ulink>. Note that this function is defined as an
     inline function. Use a declaration like the following, in order to
     allocate a bus object that is freed automatically as the code
     block is left:</para>
@@ -124,12 +124,10 @@
   …
 }</programlisting>
 
-    <para><function>sd_bus_ref()</function> and <function>sd_bus_unref()</function>
+    <para><function>sd_bus_ref()</function> and <function>sd_bus_unref()</function> execute no operation if
-    execute no operation if the passed in bus object address is
+    the argument is <constant>NULL</constant>. <function>sd_bus_unrefp()</function> will first dereference
-    <constant>NULL</constant>. <function>sd_bus_unrefp()</function> will first
+    its argument, which must not be <constant>NULL</constant>, and will execute no operation if
-    dereference its argument, which must not be <constant>NULL</constant>, and will
+    <emphasis>that</emphasis> is <constant>NULL</constant>.</para>
-    execute no operation if <emphasis>that</emphasis> is <constant>NULL</constant>.
-    </para>
 
     <para><function>sd_bus_close_unref()</function> is similar to <function>sd_bus_unref()</function>, but
     first executes

man/sd_bus_slot_ref.xml

@@ -46,10 +46,10 @@
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_bus_slot_ref()</function> increases the reference counter of
+    <para><function>sd_bus_slot_ref()</function> increases the internal reference counter of
     <parameter>slot</parameter> by one.</para>
 
-    <para><function>sd_bus_slot_unref()</function> decreases the reference counter of
+    <para><function>sd_bus_slot_unref()</function> decreases the internal reference counter of
     <parameter>slot</parameter> by one. Once the reference count has dropped to zero, slot object is
     destroyed and cannot be used anymore, so further calls to <function>sd_bus_slot_ref()</function>
     or <function>sd_bus_slot_unref()</function> are illegal.</para>

man/sd_device_ref.xml

@@ -0,0 +1,83 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="sd_device_ref" xmlns:xi="http://www.w3.org/2001/XInclude">
+  <refentryinfo>
+    <title>sd_device_ref</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_device_ref</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_device_ref</refname>
+    <refname>sd_device_unref</refname>
+    <refname>sd_device_unrefp</refname>
+
+    <refpurpose>Create or destroy references to a device object</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-device.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>sd_device* <function>sd_device_ref</function></funcdef>
+        <paramdef>sd_device *<parameter>device</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>sd_device* <function>sd_device_unref</function></funcdef>
+        <paramdef>sd_device *<parameter>device</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>void <function>sd_device_unrefp</function></funcdef>
+        <paramdef>sd_device **<parameter>device</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+
+    <para><function>sd_device_ref()</function> increases the internal reference counter of
+    <parameter>device</parameter> by one.</para>
+
+    <para><function>sd_device_unref()</function> decreases the internal reference counter of
+    <parameter>device</parameter> by one. Once the reference count has dropped to zero,
+    <parameter>device</parameter> is destroyed and cannot be used anymore, so further calls to
+    <function>sd_device_ref()</function> or <function>sd_device_unref()</function> are illegal.</para>
+
+    <para><function>sd_device_unrefp()</function> is similar to <function>sd_device_unref()</function> but
+    takes a pointer to a pointer to an <type>sd_device</type> object. This call is useful in conjunction with
+    GCC's and LLVM's <ulink url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
+    Variable Attribute</ulink>. Note that this function is defined as an inline function. Use a declaration
+    like the following, in order to allocate a device object that is freed automatically as the code block is
+    left:</para>
+
+    <programlisting>{
+  __attribute__((cleanup(sd_device_unrefp))) sd_device *device = NULL;
+  int r;
+  …
+  r = sd_device_new_from_syspath(&amp;device, "…");
+  if (r &lt; 0)
+    fprintf(stderr, "Failed to allocate device: %s\n", strerror(-r));
+  …
+}</programlisting>
+
+    <para><function>sd_device_ref()</function> and <function>sd_device_unref()</function> execute no
+    operation if the argument is <constant>NULL</constant>. <function>sd_device_unrefp()</function> will
+    first dereference its argument, which must not be <constant>NULL</constant>, and will execute no
+    operation if <emphasis>that</emphasis> is <constant>NULL</constant>.</para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para><function>sd_device_ref()</function> always returns the argument, and
+    <function>sd_device_unref()</function> always returns <constant>NULL</constant>.
+    </para>
+  </refsect1>
+</refentry>

man/sd_event_source_unref.xml

@@ -59,16 +59,13 @@
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_event_source_unref()</function> may be used to
+    <para><function>sd_event_source_unref()</function> may be used to decrement by one the internal reference
-    decrement by one the reference counter of the event source object
+    counter of the event source object specified as <parameter>source</parameter>. The reference counter is
-    specified as <parameter>source</parameter>. The reference counter
+    initially set to one, when the event source is created with calls such as
-    is initially set to one, when the event source is created with calls
+    <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
-    such as
-    <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    or
     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. When
-    the reference counter reaches zero it is removed from its event loop
+    the reference counter reaches zero, the object is detached from the event loop object and destroyed.
-    object and destroyed.</para>
+    </para>
 
     <para><function>sd_event_source_unrefp()</function> is similar to
     <function>sd_event_source_unref()</function> but takes a pointer to a
@@ -78,9 +75,8 @@
     Variable Attribute</ulink>. Note that this function is defined as
     inline function.</para>
 
-    <para><function>sd_event_source_ref()</function> may be used
+    <para><function>sd_event_source_ref()</function> may be used to increase by one the internal reference
-    to increase by one the reference counter of the event source object
+    counter of the event source object specified as <parameter>source</parameter>.</para>
-    specified as <parameter>source</parameter>.</para>
 
     <para><function>sd_event_source_unref()</function>,
     <function>sd_bus_creds_unrefp()</function> and

man/systemd-cryptenroll.xml

@@ -314,8 +314,8 @@
         its configuration. The lockout mechanism is a global property of the TPM,
         <command>systemd-cryptenroll</command> does not control or configure the lockout mechanism. You may
         use tpm2-tss tools to inspect or configure the dictionary attack lockout, with
-        <citerefentry><refentrytitle>tpm2_getcap</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
+        <citerefentry project='mankier'><refentrytitle>tpm2_getcap</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
-        <citerefentry><refentrytitle>tpm2_dictionarylockout</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        <citerefentry project='mankier'><refentrytitle>tpm2_dictionarylockout</refentrytitle><manvolnum>1</manvolnum></citerefentry>
         commands, respectively.</para></listitem>
       </varlistentry>
 

man/systemd-integritysetup@.service.xml

@@ -33,8 +33,9 @@
     protected block devices. It should be instantiated for each device that requires integrity
     protection.</para>
 
-    <para>At early boot and when the system manager configuration is reloaded, entries from /etc/integritytab are converted into
+    <para>At early boot and when the system manager configuration is reloaded, entries from
-    <filename>systemd-integritysetup@.service</filename> units by
+    <citerefentry><refentrytitle>integritytab</refentrytitle><manvolnum>5</manvolnum></citerefentry> are
+    converted into <filename>systemd-integritysetup@.service</filename> units by
     <citerefentry><refentrytitle>systemd-integritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 
     <para><filename>systemd-integritysetup@.service</filename> calls <command>systemd-integritysetup</command>.</para>
@@ -57,7 +58,7 @@
 
         <listitem><para>Create a block device <replaceable>volume</replaceable> using
         <replaceable>device</replaceable>. See
-        <citerefentry><refentrytitle>systemd-integritytab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        <citerefentry><refentrytitle>integritytab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
         and
         <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/dm-integrity.html">
           Kernel dm-integrity</ulink> documentation for details.

man/systemd-run.xml

@@ -479,7 +479,7 @@ Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisti
     <example>
       <title>Allowing access to the tty</title>
 
-      <para>The following command invokes <citerefentry><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      <para>The following command invokes <citerefentry project='die-net'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
       as a service passing its standard input, output and error to the calling TTY.</para>
 
       <programlisting># systemd-run -t --send-sighup bash</programlisting>

man/systemd-stub.xml

@@ -178,7 +178,7 @@
     <title>Assembling Kernel Images</title>
 
     <para>In order to assemble an UEFI PE kernel image from various components as described above, use an
-    <citerefentry><refentrytitle>objcopy</refentrytitle><manvolnum>1</manvolnum></citerefentry> command line
+    <citerefentry project='man-pages'><refentrytitle>objcopy</refentrytitle><manvolnum>1</manvolnum></citerefentry> command line
     like this:</para>
 
     <programlisting>objcopy \
@@ -196,7 +196,7 @@
     UEFI boot stub.</para>
 
     <para>To then sign the resulting image for UEFI SecureBoot use an
-    <citerefentry><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry> command like
+    <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry> command like
     the following:</para>
 
     <programlisting>sbsign \
@@ -219,8 +219,8 @@
       <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>,
       <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>,
-      <citerefentry><refentrytitle>objcopy</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>objcopy</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      <citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
   </refsect1>
 </refentry>

man/systemd-sysusers.xml

@@ -184,7 +184,7 @@
     for the first time, it may not be used for changing the password or shell of an account that already
     exists.</para>
 
-    <para>Use <citerefentry><refentrytitle>mkpasswd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    <para>Use <citerefentry project='man-pages'><refentrytitle>mkpasswd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     for generating UNIX password hashes from the command line.</para>
   </refsect1>
 
@@ -202,7 +202,7 @@
       <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <ulink url="https://systemd.io/UIDS-GIDS">Users, Groups, UIDs and GIDs on systemd systems</ulink>,
       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>mkpasswd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      <citerefentry project='man-pages'><refentrytitle>mkpasswd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
   </refsect1>
 

man/systemd.netdev.xml

@@ -2134,7 +2134,7 @@
         <term><varname>RoutingAlgorithm=</varname></term>
         <listitem>
           <para>This can be either <literal>batman-v</literal> or <literal>batman-iv</literal> and describes which routing_algo
-          of <citerefentry><refentrytitle>batctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> to use. The algorithm
+          of <citerefentry project='mankier'><refentrytitle>batctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> to use. The algorithm
           cannot be changed after interface creation. Defaults to <literal>batman-v</literal>.
           </para>
         </listitem>

man/udevadm.xml

@@ -800,7 +800,7 @@
       does not probe a block device while changes are made to it, for example partitions created or file
       systems formatted. Note that many tools that interface with block devices natively support taking
       relevant locks, see for example
-      <citerefentry><refentrytitle>sfdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
+      <citerefentry project='man-pages'><refentrytitle>sfdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
       <option>--lock</option> switch.</para>
 
       <para>The command expects at least one block device specified via <option>--device=</option> or