man: fix incorrect volume numbers in internal man page references

Some ambiguity (e.g., same-named man pages in multiple volumes)
makes it impossible to fully automate this, but the following
Python snippet (run inside the man/ directory of the systemd repo)
helped to generate the sed command lines (which were subsequently
manually reviewed, run and the false positives reverted):

from pathlib import Path

import lxml
from lxml import etree as ET

man2vol: dict[str, str] = {}
man2citerefs: dict[str, list] = {}

for file in Path(".").glob("*.xml"):
    tree = ET.parse(file, lxml.etree.XMLParser(recover=True))
    meta = tree.find("refmeta")
    if meta is not None:
        title = meta.findtext("refentrytitle")
        if title is not None:
            vol = meta.findtext("manvolnum")
            if vol is not None:
                man2vol[title] = vol
            citerefs = list(tree.iter("citerefentry"))
            if citerefs:
                man2citerefs[title] = citerefs

for man, refs in man2citerefs.items():
    for ref in refs:
        title = ref.findtext("refentrytitle")
        if title is not None:
            has = ref.findtext("manvolnum")
            try:
                should_have = man2vol[title]
            except KeyError:  # Non-systemd man page reference?  Ignore.
                continue
            if has != should_have:
                print(
                    f"sed -i '\\|<citerefentry><refentrytitle>{title}"
                    f"</refentrytitle><manvolnum>{has}</manvolnum>"
                    f"</citerefentry>|s|<manvolnum>{has}</manvolnum>|"
                    f"<manvolnum>{should_have}</manvolnum>|' {man}.xml"
                )

1 files changed, 2 insertions, 2 deletions

diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml
index 9e712c94c2..e6eac25180 100644
--- a/man/org.freedesktop.hostname1.xml
+++ b/man/org.freedesktop.hostname1.xml
@@ -259,7 +259,7 @@ node /org/freedesktop/hostname1 {
     are not necessary. Use
     <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
     <filename>/etc/hostname</filename> (possibly with per-distribution fallbacks), and
-    <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     for that. For more information on these files and syscalls see the respective man pages.</para>
 
     <para><varname>KernelName</varname>, <varname>KernelRelease</varname>, and
@@ -376,7 +376,7 @@ node /org/freedesktop/hostname1 {
 
     <para>To properly handle name lookups with changing local hostnames without having to edit
     <filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in combination
-    with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
     </para>
 
     <para>Here are some recommendations to follow when generating a static (internet) hostname from a pretty