doc: cross link sd_listen_fd() docs a bit

Let's make sure the sd_listen_fd() docs are really found from the
.socket file documentation as well as the FileDescriptorStoreMax=
documentation.

Let's also emphasize that that's where the order in which the fds are
passed are documented.

Fixes: #16647

3 files changed, 35 insertions, 38 deletions

diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml
index 9a66ee33ba..4973718ef6 100644
--- a/man/sd_listen_fds.xml
+++ b/man/sd_listen_fds.xml
@@ -54,24 +54,19 @@
     (i.e. <constant>SD_LISTEN_FDS_START</constant>), the remaining
     descriptors follow at 4, 5, 6, …, if any.</para>
 
-    <para>If a daemon receives more than one file descriptor, they
-    will be passed in the same order as configured in the systemd
-    socket unit file (see
-    <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-    for details). Nonetheless, it is recommended to verify the correct
-    socket types before using them. To simplify this checking, the
-    functions
+    <para>If a daemon receives more than one file descriptor, they will be passed in the same order as
+    configured in the systemd socket unit file (see
+    <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+    details) — if there's only one such file (see below).  Nonetheless, it is recommended to verify the
+    correct socket types before using them. To simplify this checking, the functions
     <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-    <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    are provided. In order to maximize flexibility, it is recommended
-    to make these checks as loose as possible without allowing
-    incorrect setups. i.e. often, the actual port number a socket is
-    bound to matters little for the service to work, hence it should
-    not be verified. On the other hand, whether a socket is a datagram
-    or stream socket matters a lot for the most common program logics
-    and should be checked.</para>
+    <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry> are
+    provided. In order to maximize flexibility, it is recommended to make these checks as loose as possible
+    without allowing incorrect setups. i.e. often, the actual port number a socket is bound to matters little
+    for the service to work, hence it should not be verified. On the other hand, whether a socket is a
+    datagram or stream socket matters a lot for the most common program logics and should be checked.</para>
 
     <para>This function call will set the FD_CLOEXEC flag for all
     passed file descriptors to avoid further inheritance to children
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 5aec511724..124fa383ab 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -1028,20 +1028,24 @@
 
       <varlistentry>
         <term><varname>FileDescriptorStoreMax=</varname></term>
-        <listitem><para>Configure how many file descriptors may be stored in the service manager for the service using
+        <listitem><para>Configure how many file descriptors may be stored in the service manager for the
+        service using
         <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
-        <literal>FDSTORE=1</literal> messages. This is useful for implementing services that can restart after an
-        explicit request or a crash without losing state. Any open sockets and other file descriptors which should not
-        be closed during the restart may be stored this way. Application state can either be serialized to a file in
-        <filename>/run</filename>, or better, stored in a
-        <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory file
-        descriptor. Defaults to 0, i.e. no file descriptors may be stored in the service manager. All file descriptors
-        passed to the service manager from a specific service are passed back to the service's main process on the next
-        service restart. Any file descriptors passed to the service manager are automatically closed when
-        <constant>POLLHUP</constant> or <constant>POLLERR</constant> is seen on them, or when the service is fully
-        stopped and no job is queued or being executed for it. If this option is used, <varname>NotifyAccess=</varname>
-        (see above) should be set to open access to the notification socket provided by systemd. If
-        <varname>NotifyAccess=</varname> is not set, it will be implicitly set to
+        <literal>FDSTORE=1</literal> messages. This is useful for implementing services that can restart
+        after an explicit request or a crash without losing state. Any open sockets and other file
+        descriptors which should not be closed during the restart may be stored this way. Application state
+        can either be serialized to a file in <filename>/run</filename>, or better, stored in a
+        <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+        memory file descriptor. Defaults to 0, i.e. no file descriptors may be stored in the service
+        manager. All file descriptors passed to the service manager from a specific service are passed back
+        to the service's main process on the next service restart (see
+        <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
+        details about the precise protocol used and the order in which the file descriptors are passed). Any
+        file descriptors passed to the service manager are automatically closed when
+        <constant>POLLHUP</constant> or <constant>POLLERR</constant> is seen on them, or when the service is
+        fully stopped and no job is queued or being executed for it. If this option is used,
+        <varname>NotifyAccess=</varname> (see above) should be set to open access to the notification socket
+        provided by systemd. If <varname>NotifyAccess=</varname> is not set, it will be implicitly set to
         <option>main</option>.</para></listitem>
       </varlistentry>
 
diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml
index f989b99f95..29ce0b1c20 100644
--- a/man/systemd.socket.xml
+++ b/man/systemd.socket.xml
@@ -81,16 +81,14 @@
     services, as well as parallelized starting of services. See the
     blog stories linked at the end for an introduction.</para>
 
-    <para>Note that the daemon software configured for socket
-    activation with socket units needs to be able to accept sockets
-    from systemd, either via systemd's native socket passing interface
-    (see
-    <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    for details) or via the traditional
-    <citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
-    socket passing (i.e. sockets passed in via standard input and
-    output, using <varname>StandardInput=socket</varname> in the
-    service file).</para>
+    <para>Note that the daemon software configured for socket activation with socket units needs to be able
+    to accept sockets from systemd, either via systemd's native socket passing interface (see
+    <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
+    details about the precise protocol used and the order in which the file descriptors are passed) or via
+    traditional <citerefentry
+    project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
+    socket passing (i.e. sockets passed in via standard input and output, using
+    <varname>StandardInput=socket</varname> in the service file).</para>
 
     <para>All network sockets allocated through <filename>.socket</filename> units are allocated in the host's network
     namespace (see <citerefentry