From 87291a26f5262c47bdb3493d15534c18f25870e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Tue, 7 Mar 2023 13:48:09 +0100
Subject: [PATCH] man: explain route-only domains a bit more
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The details discussion of how search and route-only domains work is in
systemd-resolved.service(8). But users are more likely to look at
resolved.conf(5), because that's where Domains= is described. So let's add a
reference to the other man page there, and also strengthen the text a bit. In
particular, in systemd-resolved.service(8) we say "route-only", which makes
the distinction with search domains clearer. Let's use the same in the other
man page too.

This is based on feedback from Lukáš Nykrýn that the man page is not clear
enough.
---
 man/resolved.conf.xml | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml
index 3c56b76748..2b9f482971 100644
--- a/man/resolved.conf.xml
+++ b/man/resolved.conf.xml
@@ -75,7 +75,7 @@
 
       <varlistentry>
         <term><varname>Domains=</varname></term>
-        <listitem><para>A space-separated list of domains optionally prefixed with <literal>~</literal>,
+        <listitem><para>A space-separated list of domains, optionally prefixed with <literal>~</literal>,
         used for two distinct purposes described below. Defaults to the empty list.</para>
 
         <para>Any domains <emphasis>not</emphasis> prefixed with <literal>~</literal> are used as search
@@ -86,17 +86,23 @@
         <filename>/etc/resolv.conf</filename> with the <varname>search</varname> keyword are used instead, if
         that file exists and any domains are configured in it.</para>
 
-        <para>The domains prefixed with <literal>~</literal> are called "routing domains". All domains listed
-        here (both search domains and routing domains after removing the <literal>~</literal> prefix) define
-        a search path that preferably directs DNS queries to this interface. This search path has an effect
-        only when suitable per-link DNS servers are known. Such servers may be defined through the
-        <varname>DNS=</varname> setting (see above) and dynamically at run time, for example from DHCP
-        leases. If no per-link DNS servers are known, routing domains have no effect.</para>
+        <para>The domains prefixed with <literal>~</literal> are called "route-only domains". All domains
+        listed here (<emphasis>both search domains and route-only domains</emphasis> after removing the
+        <literal>~</literal> prefix) define a search path that preferably directs DNS queries to this
+        interface. This search path has an effect only when suitable per-link DNS servers are known. Such
+        servers may be defined through the <varname>DNS=</varname> setting (see above) and dynamically at run
+        time, for example from DHCP leases. If no per-link DNS servers are known, route-only domains have no
+        effect.</para>
 
         <para>Use the construct <literal>~.</literal> (which is composed from <literal>~</literal> to
-        indicate a routing domain and <literal>.</literal> to indicate the DNS root domain that is the
+        indicate a route-only domain and <literal>.</literal> to indicate the DNS root domain that is the
         implied suffix of all DNS domains) to use the DNS servers defined for this link preferably for all
-        domains.</para></listitem>
+        domains.</para>
+
+        <para>See "Protocols and Routing" in
+        <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        for details of how search and route-only domains are used.</para>
+        </listitem>
       </varlistentry>
 
       <varlistentry>