man: rework description of Domains=

We said that ~domains "do not define a search path", which is mighty confusing,
because this is exactly what they do. So let's try to make this a bit easier
for the reader: start by saying that there are two things going on here, and
describe each one from user's POV.

1 files changed, 22 insertions, 14 deletions

diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml
index 9be41baaa5..33265f755c 100644
--- a/man/resolved.conf.xml
+++ b/man/resolved.conf.xml
@@ -67,20 +67,28 @@
 
       <varlistentry>
         <term><varname>Domains=</varname></term>
-        <listitem><para>A space-separated list of domains. These domains are used as search suffixes when resolving
-        single-label hostnames (domain names which contain no dot), in order to qualify them into fully-qualified
-        domain names (FQDNs). Search domains are strictly processed in the order they are specified, until the name
-        with the suffix appended is found. For compatibility reasons, if this setting is not specified, the search
-        domains listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any domains
-        are configured in it. This setting defaults to the empty list.</para>
-
-        <para>Specified domain names may optionally be prefixed with <literal>~</literal>. In this case they do not
-        define a search path, but preferably direct DNS queries for the indicated domains to the DNS servers configured
-        with the system <varname>DNS=</varname> setting (see above), in case additional, suitable per-link DNS servers
-        are known. If no per-link DNS servers are known using the <literal>~</literal> syntax has no effect. Use the
-        construct <literal>~.</literal> (which is composed of <literal>~</literal> to indicate a routing domain and
-        <literal>.</literal> to indicate the DNS root domain that is the implied suffix of all DNS domains) to use the
-        system DNS server defined with <varname>DNS=</varname> preferably for all domains.</para></listitem>
+        <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
+        suffixes when resolving single-label hostnames (domain names which contain no dot), in order to
+        qualify them into fully-qualified domain names (FQDNs). These "search domains" are strictly processed
+        in the order they are specified in, until the name with the suffix appended is found. For
+        compatibility reasons, if this setting is not specified, the search domains listed in
+        <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 inteface. 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>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
+        implied suffix of all DNS domains) to use the DNS servers defined for this link preferably for all
+        domains.</para></listitem>
       </varlistentry>
 
       <varlistentry>