man: use meaningful titles for <ulink>s

As pointed out in https://github.com/systemd/systemd/issues/29814, we need to
use phrases are are meaningful on their own, because the man page formatter
creates a list at the bottom. With <ulink>see docs</ulink>, we end up with:
  NOTES:
    1. see docs
       https://some.url/page
    2. see docs
       https://some.url/page2
which is not very useful :(

Also, the text inside the tag should not include punctuation.

Python helper:
  from xml_helper import xml_parse
  for p in glob.glob('../man/*.xml'):
       t = xml_parse(p)
       ulinks = t.iterfind('.//ulink')
       for ulink in ulinks:
           if ulink.text is None: continue
           text = ' '.join(ulink.text.split())
           print(f'{p}: {text}')

12 files changed, 73 insertions, 64 deletions

diff --git a/man/crypttab.xml b/man/crypttab.xml
index fa60599301..e94bf1ca17 100644
--- a/man/crypttab.xml
+++ b/man/crypttab.xml
@@ -556,8 +556,9 @@
         <para>Note that VeraCrypt enforces a minimal allowed PIM value depending on the
         password strength and the hash algorithm used for key derivation, however
         <option>veracrypt-pim=</option> is not checked against these bounds.
-        <ulink url="https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html">See
-        documentation</ulink> for more information.</para>
+        See
+        <ulink url="https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html">Veracrypt Personal Iterations Multiplier</ulink>
+        documentation for more information.</para>
 
         <xi:include href="version-info.xml" xpointer="v254"/>
         </listitem>
@@ -980,8 +981,9 @@ external   /dev/sda3       keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchac
       <itemizedlist>
         <listitem><para>We use RSA2048, which is the longest key size current Yubikeys support</para></listitem>
         <listitem><para>We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes,
-        <ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">see
-        documentation</ulink>.</para></listitem>
+        see
+        <ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">Yubico PIV certificate slots</ulink>.
+        </para></listitem>
       </itemizedlist>
     </example>
 
diff --git a/man/resolvectl.xml b/man/resolvectl.xml
index 549dbbd2b7..4498732656 100644
--- a/man/resolvectl.xml
+++ b/man/resolvectl.xml
@@ -77,17 +77,17 @@
         [[<replaceable>NAME</replaceable>] <replaceable>TYPE</replaceable>]
         <replaceable>DOMAIN</replaceable></term>
 
-        <listitem><para>Resolve <ulink url="https://tools.ietf.org/html/rfc6763">DNS-SD</ulink> and <ulink
-        url="https://tools.ietf.org/html/rfc2782">SRV</ulink> services, depending on the specified list of
-        parameters.  If three parameters are passed the first is assumed to be the DNS-SD service name, the
-        second the <constant class='dns'>SRV</constant> service type, and the third the domain to search in.
-        In this case a full DNS-SD style <constant class='dns'>SRV</constant> and <constant
-        class='dns'>TXT</constant> lookup is executed. If only two parameters are specified, the first is
-        assumed to be the <constant class='dns'>SRV</constant> service type, and the second the domain to look
-        in. In this case no <constant class='dns'>TXT</constant> resource record is requested. Finally, if
-        only one parameter is specified, it is assumed to be a domain name, that is already prefixed with an
-        <constant class='dns'>SRV</constant> type, and an <constant class='dns'>SRV</constant> lookup is done
-        (no <constant class='dns'>TXT</constant>).</para>
+        <listitem><para>Resolve <ulink url="https://tools.ietf.org/html/rfc6763">RFC 6763 DNS-SD</ulink> and
+        <ulink url="https://tools.ietf.org/html/rfc2782">RFC 2782 SRV</ulink> services, depending on the
+        specified list of parameters. If three parameters are passed the first is assumed to be the DNS-SD
+        service name, the second the <constant class='dns'>SRV</constant> service type, and the third the
+        domain to search in. In this case a full DNS-SD style <constant class='dns'>SRV</constant> and
+        <constant class='dns'>TXT</constant> lookup is executed. If only two parameters are specified, the
+        first is assumed to be the <constant class='dns'>SRV</constant> service type, and the second the
+        domain to look in. In this case no <constant class='dns'>TXT</constant> resource record is requested.
+        Finally, if only one parameter is specified, it is assumed to be a domain name, that is already
+        prefixed with an <constant class='dns'>SRV</constant> type, and an <constant
+        class='dns'>SRV</constant> lookup is done (no <constant class='dns'>TXT</constant>).</para>
 
         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
       </varlistentry>
diff --git a/man/sd-id128.xml b/man/sd-id128.xml
index 4021b8844b..d264220b0b 100644
--- a/man/sd-id128.xml
+++ b/man/sd-id128.xml
@@ -190,7 +190,7 @@ int main(int argc, char **argv) {
     are similar to
     <constant>SD_ID128_FORMAT_STR</constant> and <function>SD_ID128_MAKE_STR()</function>,
     but include separating hyphens to conform to the
-    "<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical representation</ulink>".
+    "<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">UUID canonical representation</ulink>".
     They format the string based on <ulink
     url="https://tools.ietf.org/html/rfc4122">RFC4122</ulink> Variant 1 rules, i.e. converting from Big
     Endian byte order. This matches behaviour of most other Linux userspace infrastructure. It's probably
diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml
index 847051a6a2..3f7a28ccaf 100644
--- a/man/sd_bus_error.xml
+++ b/man/sd_bus_error.xml
@@ -163,7 +163,7 @@
       <listitem><para>The <structfield>name</structfield> field contains a short identifier of an error. It
       should follow the rules for error names described in the D-Bus specification, subsection <ulink
       url="https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
-      Names</ulink>. A number of common, standardized error names are described in
+      D-Bus Names</ulink>. A number of common, standardized error names are described in
       <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but
       additional domain-specific errors may be defined by applications.</para></listitem>
 
diff --git a/man/sd_bus_message_append_array.xml b/man/sd_bus_message_append_array.xml
index da72b78cb0..ea8f532ab6 100644
--- a/man/sd_bus_message_append_array.xml
+++ b/man/sd_bus_message_append_array.xml
@@ -80,7 +80,7 @@
     <literal>t</literal>, <literal>d</literal> (but not
     <literal>b</literal>), as defined by the <ulink
     url="https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic
-    Types</ulink> section of the D-Bus specification, and listed in
+    D-Bus Types</ulink> section of the D-Bus specification, and listed in
     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
     Pointer <parameter>p</parameter> must point to an array of size
     <parameter>size</parameter> bytes containing items of the
diff --git a/man/sd_bus_set_description.xml b/man/sd_bus_set_description.xml
index 0cc0ee77e9..0b49ba3a3b 100644
--- a/man/sd_bus_set_description.xml
+++ b/man/sd_bus_set_description.xml
@@ -121,7 +121,7 @@
     i.e. lack of authentication, of the bus peer. This function must be called before the bus is
     started. See the
     <ulink url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms">
-    Authentication Mechanisms</ulink> section of the D-Bus specification for details.</para>
+    D-Bus Authentication Mechanisms</ulink> section of the D-Bus specification for details.</para>
 
     <para><function>sd_bus_is_anonymous()</function> returns true if the bus connection allows
     anonymous authentication (in the sense described in previous paragraph).</para>
diff --git a/man/systemd-id128.xml b/man/systemd-id128.xml
index 32c5af9671..d9378b69df 100644
--- a/man/systemd-id128.xml
+++ b/man/systemd-id128.xml
@@ -137,8 +137,8 @@
         <term><option>--uuid</option></term>
 
         <listitem><para>Generate output as a UUID formatted in the "canonical representation", with five
-        groups of digits separated by hyphens. See the
-        <ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">wikipedia</ulink>
+        groups of digits separated by hyphens. See the Wikipedia entry for
+        <ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">Universally Unique Identifiers</ulink>
         for more discussion.</para>
 
         <xi:include href="version-info.xml" xpointer="v244"/></listitem>
diff --git a/man/systemd-sleep.conf.xml b/man/systemd-sleep.conf.xml
index 4a04263c1a..ee13ce8703 100644
--- a/man/systemd-sleep.conf.xml
+++ b/man/systemd-sleep.conf.xml
@@ -153,9 +153,9 @@
         be aborted.</para>
 
         <para>The allowed set of values is determined by the kernel and is shown in the file itself (use
-        <command>cat /sys/power/disk</command> to display). See <ulink
-        url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">the
-        kernel documentation</ulink> for more details.</para>
+        <command>cat /sys/power/disk</command> to display). See the kernel documentation page
+        <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">
+          Basic sysfs Interfaces for System Suspend and Hibernation</ulink> for more details.</para>
 
         <para>
         <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
@@ -175,8 +175,8 @@
 
         <para>The allowed set of values is determined by the kernel and is shown in the file itself (use
         <command>cat /sys/power/state</command> to display). See <ulink
-        url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">the
-        kernel documentation</ulink> for more details.</para>
+        url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">
+          Basic sysfs Interfaces for System Suspend and Hibernation</ulink> for more details.</para>
 
         <para>
         <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml
index ac2be5a5c2..3c06b65f93 100644
--- a/man/systemd-system.conf.xml
+++ b/man/systemd-system.conf.xml
@@ -461,8 +461,8 @@
         case of the system manager, this includes variables set by the kernel based on the kernel command line.</para>
 
         <para>Setting environment variables for the manager process may be useful to modify its behaviour.
-        See <ulink url="https://systemd.io/ENVIRONMENT">ENVIRONMENT</ulink> for a descriptions of some
-        variables understood by <command>systemd</command>.</para>
+        See <ulink url="https://systemd.io/ENVIRONMENT">Known Environment Variables</ulink> for a
+        descriptions of some variables understood by <command>systemd</command>.</para>
 
         <para>Simple <literal>%</literal>-specifier expansion is supported, see below for a list of supported
         specifiers.</para>
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index e9cef24d18..f5d68f6c47 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -166,8 +166,9 @@
         or loopback file instead of a directory. The device node or file system image file needs to contain a
         file system without a partition table, or a file system within an MBR/MS-DOS or GPT partition table
         with only a single Linux-compatible partition, or a set of file systems within a GPT partition table
-        that follows the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
-        Specification</ulink>.</para>
+        that follows the
+        <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
+          Discoverable Partitions Specification</ulink>.</para>
 
         <para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or
         <literal>strict</literal>, or set to <literal>auto</literal> and <varname>DeviceAllow=</varname> is
@@ -207,8 +208,9 @@
         <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
         </para>
 
-        <para>Valid partition names follow the <ulink
-        url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>:
+        <para>Valid partition names follow the
+        <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
+          Discoverable Partitions Specification</ulink>:
         <constant>root</constant>, <constant>usr</constant>, <constant>home</constant>, <constant>srv</constant>,
         <constant>esp</constant>, <constant>xbootldr</constant>, <constant>tmp</constant>,
         <constant>var</constant>.</para>
@@ -302,8 +304,9 @@
 
         <para>This option is supported only for disk images that contain a single file system, without an
         enveloping partition table. Images that contain a GPT partition table should instead include both
-        root file system and matching Verity data in the same image, implementing the <ulink
-        url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>.</para>
+        root file system and matching Verity data in the same image, implementing the
+        <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
+          Discoverable Partitions Specification</ulink>.</para>
 
         <xi:include href="system-only.xml" xpointer="singular"/>
 
@@ -831,9 +834,10 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
         <varname>SystemCallFilter=</varname>, or <varname>SystemCallLog=</varname> are specified. Note that
         even if this setting is overridden by them, <command>systemctl show</command> shows the original
         value of this setting. In case the service will be run in a new mount namespace anyway and SELinux is
-        disabled, all file systems are mounted with <constant>MS_NOSUID</constant> flag. Also see <ulink
-        url="https://docs.kernel.org/userspace-api/no_new_privs.html">No New Privileges
-        Flag</ulink>.</para>
+        disabled, all file systems are mounted with <constant>MS_NOSUID</constant> flag. Also see
+        the kernel document
+        <ulink url="https://docs.kernel.org/userspace-api/no_new_privs.html">No New Privileges Flag</ulink>.
+        </para>
 
         <para>Note that this setting only has an effect on the unit's processes themselves (or any processes
         directly or indirectly forked off them). It has no effect on processes potentially invoked on request
@@ -2787,37 +2791,39 @@ SystemCallErrorNumber=EPERM</programlisting>
         <listitem><para>Similar to <varname>Environment=</varname>, but reads the environment variables from
         a text file. The text file should contain newline-separated variable assignments. Empty lines, lines
         without an <literal>=</literal> separator, or lines starting with <literal>;</literal> or
-        <literal>#</literal> will be ignored, which may be used for commenting. The file must be UTF-8
-        encoded. Valid characters are <ulink
-        url="https://www.unicode.org/glossary/#unicode_scalar_value">unicode scalar values</ulink> other than
-        <ulink url="https://www.unicode.org/glossary/#noncharacter">noncharacters</ulink>, U+0000 NUL, and
-        U+FEFF <ulink url="https://www.unicode.org/glossary/#byte_order_mark">byte order mark</ulink>.
-        Control codes other than NUL are allowed.</para>
+        <literal>#</literal> will be ignored, which may be used for commenting. The file must be encoded with
+        UTF-8. Valid characters are
+        <ulink url="https://www.unicode.org/glossary/#unicode_scalar_value">unicode scalar values</ulink>
+        other than
+        <ulink url="https://www.unicode.org/glossary/#noncharacter">unicode noncharacters</ulink>,
+        <constant>U+0000</constant> <constant>NUL</constant>, and <constant>U+FEFF</constant>
+        <ulink url="https://www.unicode.org/glossary/#byte_order_mark">unicode byte order mark</ulink>.
+        Control codes other than <constant>NUL</constant> are allowed.</para>
 
         <para>In the file, an unquoted value after the <literal>=</literal> is parsed with the same backslash-escape
         rules as <ulink
-        url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01">unquoted
-        text</ulink> in a POSIX shell, but unlike in a shell, interior whitespace is preserved and quotes after the
+        url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01">POSIX shell unquoted
+        text</ulink>, but unlike in a shell, interior whitespace is preserved and quotes after the
         first non-whitespace character are preserved. Leading and trailing whitespace (space, tab, carriage return) is
         discarded, but interior whitespace within the line is preserved verbatim. A line ending with a backslash will be
         continued to the following one, with the newline itself discarded. A backslash
         <literal>\</literal> followed by any character other than newline will preserve the following character, so that
         <literal>\\</literal> will become the value <literal>\</literal>.</para>
 
-        <para>In the file, a <literal>'</literal>-quoted value after the <literal>=</literal> can span multiple lines
-        and contain any character verbatim other than single quote, like <ulink
-        url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02">single-quoted
-        text</ulink> in a POSIX shell. No backslash-escape sequences are recognized. Leading and trailing whitespace
-        outside of the single quotes is discarded.</para>
-
-        <para>In the file, a <literal>"</literal>-quoted value after the <literal>=</literal> can span multiple lines,
-        and the same escape sequences are recognized as in <ulink
-        url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03">double-quoted
-        text</ulink> of a POSIX shell. Backslash (<literal>\</literal>) followed by any of <literal>"\`$</literal> will
-        preserve that character. A backslash followed by newline is a line continuation, and the newline itself is
-        discarded. A backslash followed by any other character is ignored; both the backslash and the following
-        character are preserved verbatim. Leading and trailing whitespace outside of the double quotes is
-        discarded.</para>
+        <para>In the file, a <literal>'</literal>-quoted value after the <literal>=</literal> can span
+        multiple lines and contain any character verbatim other than single quote, like <ulink
+        url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02">POSIX
+        shell single-quoted text</ulink>. No backslash-escape sequences are recognized. Leading and trailing
+        whitespace outside of the single quotes is discarded.</para>
+
+        <para>In the file, a <literal>"</literal>-quoted value after the <literal>=</literal> can span
+        multiple lines, and the same escape sequences are recognized as in <ulink
+        url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03">POSIX
+        shell double-quoted text</ulink>. Backslash (<literal>\</literal>) followed by any of
+        <literal>"\`$</literal> will preserve that character. A backslash followed by newline is a line
+        continuation, and the newline itself is discarded. A backslash followed by any other character is
+        ignored; both the backslash and the following character are preserved verbatim. Leading and trailing
+        whitespace outside of the double quotes is discarded.</para>
 
         <para>The argument passed should be an absolute filename or wildcard expression, optionally prefixed with
         <literal>-</literal>, which indicates that if the file does not exist, it will not be read and no error or
diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml
index 2d3e575a8b..9cad358f1e 100644
--- a/man/systemd.netdev.xml
+++ b/man/systemd.netdev.xml
@@ -712,11 +712,11 @@
       <varlistentry>
         <term><varname>ReduceARPProxy=</varname></term>
         <listitem>
-          <para>Takes a boolean. When true, bridge-connected VXLAN tunnel
-          endpoint answers ARP requests from the local bridge on behalf
-          of remote Distributed Overlay Virtual Ethernet
+          <para>Takes a boolean. When true, bridge-connected VXLAN tunnel endpoint answers ARP requests from
+          the local bridge on behalf of remote
           <ulink url="https://en.wikipedia.org/wiki/Distributed_Overlay_Virtual_Ethernet">
-          (DOVE)</ulink> clients. Defaults to false.</para>
+            Distributed Overlay Virtual Ethernet (DOVE)</ulink>
+          clients. Defaults to false.</para>
 
           <xi:include href="version-info.xml" xpointer="v233"/>
         </listitem>
diff --git a/man/udev.xml b/man/udev.xml
index 0f524697c0..709cecfd6a 100644
--- a/man/udev.xml
+++ b/man/udev.xml
@@ -136,7 +136,8 @@
           backslash, lowercase t, backslash, lowercase n.</para>
 
           <para>The string can be prefixed with a lowercase e (e"string\n") to mark the string as
-          <ulink url="https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences">C-style escaped</ulink>.
+          C-style escaped, see
+          <ulink url="https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences">Escape sequences in C</ulink>.
           For example, e"string\n" is parsed as 7 characters: 6 lowercase letters and a newline.
           This can be useful for writing special characters when a kernel driver requires them.</para>