man: add markup to dns resource record labels

4 files changed, 102 insertions, 89 deletions

diff --git a/man/dnssec-trust-anchors.d.xml b/man/dnssec-trust-anchors.d.xml
index d2f2f9b0ea..b0e95ce841 100644
--- a/man/dnssec-trust-anchors.d.xml
+++ b/man/dnssec-trust-anchors.d.xml
@@ -43,12 +43,10 @@
   <refsect1>
     <title>Positive Trust Anchors</title>
 
-    <para>Positive trust anchor configuration files contain DNSKEY and
-    DS resource record definitions to use as base for DNSSEC integrity
-    proofs. See <ulink
-    url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035,
-    Section 4.4</ulink> for more information about DNSSEC trust
-    anchors.</para>
+    <para>Positive trust anchor configuration files contain <constant class='dns'>DNSKEY</constant> and
+    <constant class='dns'>DS</constant> resource record definitions to use as base for DNSSEC integrity
+    proofs. See <ulink url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, Section 4.4</ulink>
+    for more information about DNSSEC trust anchors.</para>
 
     <para>Positive trust anchors are read from files with the suffix
     <filename>.positive</filename> located in
@@ -65,10 +63,11 @@
     empty or a symlink to <filename>/dev/null</filename> ("masked").</para>
 
     <para>Positive trust anchor files are simple text files resembling DNS zone files, as documented in
-    <ulink url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section 5</ulink>. One DS or DNSKEY
-    resource record may be listed per line. Empty lines and lines starting with <literal>#</literal> or
-    <literal>;</literal> are ignored, which may be used for commenting. A DS resource record is specified
-    like in the following example:</para>
+    <ulink url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section 5</ulink>. One <constant
+    class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> resource record may be listed per
+    line. Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are ignored, which
+    may be used for commenting. A <consant class='dns'>DS</consant> resource record is specified like in the
+    following example:</para>
 
     <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting>
 
@@ -83,24 +82,20 @@
     Section 5</ulink> for details about the precise syntax and meaning
     of these fields.</para>
 
-    <para>Alternatively, DNSKEY resource records may be used to define
-    trust anchors, like in the following example:</para>
+    <para>Alternatively, <constant class='dns'>DNSKEY</constant> resource records may be used to define trust
+    anchors, like in the following example:</para>
 
     <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting>
 
-    <para>The first word specifies the domain again, the second word
-    must be <literal>IN</literal>, followed by
-    <literal>DNSKEY</literal>. The subsequent words encode the DNSKEY
-    flags, protocol and algorithm fields, followed by the key data
-    encoded in Base64. See <ulink
-    url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034,
-    Section 2</ulink> for details about the precise syntax and meaning
-    of these fields.</para>
+    <para>The first word specifies the domain again, the second word must be <literal>IN</literal>, followed
+    by <literal>DNSKEY</literal>. The subsequent words encode the <constant class='dns'>DNSKEY</constant>
+    flags, protocol and algorithm fields, followed by the key data encoded in Base64. See <ulink
+    url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, Section 2</ulink> for details about the
+    precise syntax and meaning of these fields.</para>
 
-    <para>If multiple DS or DNSKEY records are defined for the same
-    domain (possibly even in different trust anchor files), all keys
-    are used and are considered equivalent as base for DNSSEC
-    proofs.</para>
+    <para>If multiple <constant class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> records
+    are defined for the same domain (possibly even in different trust anchor files), all keys are used and
+    are considered equivalent as base for DNSSEC proofs.</para>
 
     <para>Note that <filename>systemd-resolved</filename> will
     automatically use a built-in trust anchor key for the Internet
@@ -110,17 +105,15 @@
     as soon as at least one trust anchor key for the root domain is
     defined in trust anchor files.</para>
 
-    <para>It is generally recommended to encode trust anchors in DS
-    resource records, rather than DNSKEY resource records.</para>
-
-    <para>If a trust anchor specified via a DS record is found revoked
-    it is automatically removed from the trust anchor database for the
-    runtime. See <ulink url="https://tools.ietf.org/html/rfc5011">RFC
-    5011</ulink> for details about revoked trust anchors. Note that
-    <filename>systemd-resolved</filename> will not update its trust
-    anchor database from DNS servers automatically. Instead, it is
-    recommended to update the resolver software or update the new
-    trust anchor via adding in new trust anchor files.</para>
+    <para>It is generally recommended to encode trust anchors in <constant class='dns'>DS</constant> resource
+    records, rather than <constant class='dns'>DNSKEY</constant> resource records.</para>
+
+    <para>If a trust anchor specified via a <constant class='dns'>DS</constant> record is found revoked it is
+    automatically removed from the trust anchor database for the runtime. See <ulink
+    url="https://tools.ietf.org/html/rfc5011">RFC 5011</ulink> for details about revoked trust anchors. Note
+    that <filename>systemd-resolved</filename> will not update its trust anchor database from DNS servers
+    automatically. Instead, it is recommended to update the resolver software or update the new trust anchor
+    via adding in new trust anchor files.</para>
 
     <para>The current DNSSEC trust anchor for the Internet's root
     domain is available at the <ulink
diff --git a/man/org.freedesktop.resolve1.xml b/man/org.freedesktop.resolve1.xml
index 860a14877d..78a52cc67d 100644
--- a/man/org.freedesktop.resolve1.xml
+++ b/man/org.freedesktop.resolve1.xml
@@ -308,12 +308,15 @@ node /org/freedesktop/resolve1 {
       records of many types, it is crucial that clients using this API understand that the RR data originates
       from the network and should be thoroughly validated before use.</para>
 
-      <para><function>ResolveService()</function> may be used to resolve a DNS SRV service record, as well as the
-      hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional
-      service metadata. The primary benefit of using this method over <function>ResolveRecord()</function>
-      specifying the SRV type is that it will resolve the SRV and TXT RRs as well as the hostnames referenced
-      in the SRV in a single operation. As parameters it takes a Linux network interface index, a service
-      name, a service type and a service domain. This method may be invoked in three different modes:</para>
+      <para><function>ResolveService()</function> may be used to resolve a DNS
+      <constant class="dns">SRV</constant> service record, as well as the hostnames referenced in it, and
+      possibly an accompanying DNS-SD <constant class="dns">TXT</constant> record containing additional
+      service metadata.  The primary benefit of using this method over <function>ResolveRecord()</function>
+      specifying the <constant class="dns">SRV</constant> type is that it will resolve the
+      <constant class="dns">SRV</constant> and <constant class="dns">TXT</constant> RRs as well as the
+      hostnames referenced in the SRV in a single operation. As parameters it takes a Linux network interface
+      index, a service name, a service type and a service domain. This method may be invoked in three
+      different modes:</para>
 
       <orderedlist>
         <listitem><para>To resolve a DNS-SD service, specify the service name (e.g. <literal>Lennart's
@@ -323,13 +326,13 @@ node /org/freedesktop/resolve1 {
         specifications). However, if necessary, IDNA conversion is applied to the domain parameter.</para>
         </listitem>
 
-        <listitem><para>To resolve a plain SRV record, set the service name parameter to the empty string
-        and set the service type and domain properly. (IDNA conversion is applied to the domain, if
-        necessary.)</para></listitem>
+        <listitem><para>To resolve a plain <constant class="dns">SRV</constant> record, set the service name
+        parameter to the empty string and set the service type and domain properly. (IDNA conversion is
+        applied to the domain, if necessary.)</para></listitem>
 
-        <listitem><para>Alternatively, leave both the service name and type empty and specify the full
-        domain name of the SRV record (i.e. prefixed with the service type) in the domain parameter. (No IDNA
-        conversion is applied in this mode.)</para></listitem>
+        <listitem><para>Alternatively, leave both the service name and type empty and specify the full domain
+        name of the <constant class="dns">SRV</constant> record (i.e. prefixed with the service type) in the
+        domain parameter. (No IDNA conversion is applied in this mode.)</para></listitem>
       </orderedlist>
 
       <para>The <varname>family</varname> parameter of the <function>ResolveService()</function> method encodes
@@ -339,15 +342,16 @@ node /org/freedesktop/resolve1 {
       <varname>flags</varname> parameter takes a couple of flags that may be used to alter the resolver
       operation.</para>
 
-      <para>On completion, <function>ResolveService()</function> returns an array of SRV record structures. Each
-      items consisting of the priority, weight and port fields as well as the hostname to contact, as encoded in the SRV
+      <para>On completion, <function>ResolveService()</function> returns an array of
+      <constant class="dns">SRV</constant> record structures. Each items consisting of the priority, weight and port
+      fields as well as the hostname to contact, as encoded in the <constant class="dns">SRV</constant>
       record. Immediately following is an array of the addresses of this hostname, with each item consisting
       of the interface index, the address family and the address data in a byte array. This address array is
-      followed by the canonicalized hostname. After this array of SRV record structures an array of byte
-      arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters
-      are the canonical service name, type and domain. This may or may not be identical to the parameters
-      passed in. Finally, a <varname>flags</varname> field is returned that contains information about the
-      resolver operation performed.</para>
+      followed by the canonicalized hostname. After this array of <constant class="dns">SRV</constant> record
+      structures an array of byte arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are
+      enabled. The next parameters are the canonical service name, type and domain. This may or may not be
+      identical to the parameters passed in. Finally, a <varname>flags</varname> field is returned that
+      contains information about the resolver operation performed.</para>
 
       <para>The <function>ResetStatistics()</function> method resets the various statistics counters that
       <filename>systemd-resolved</filename> maintains to zero. (For details, see the statistics properties below.)</para>
@@ -779,8 +783,8 @@ node /org/freedesktop/resolve1/link/_1 {
       </varlistentry>
 
       <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchService</constant></term>
-      <listitem><para>A service look-up was successful, but the SRV record reported that the service is not
-      available.</para></listitem></varlistentry>
+      <listitem><para>A service look-up was successful, but the <constant class="dns">SRV</constant> record
+      reported that the service is not available.</para></listitem></varlistentry>
 
       <varlistentry><term><constant>org.freedesktop.resolve1.DnssecFailed</constant></term>
       <listitem><para>The acquired response did not pass DNSSEC validation.</para></listitem>
diff --git a/man/resolvectl.xml b/man/resolvectl.xml
index bd1a636d60..b9c4d1d768 100644
--- a/man/resolvectl.xml
+++ b/man/resolvectl.xml
@@ -75,21 +75,26 @@
         [[<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 SRV service type,
-        and the third the domain to search in. In this case a full DNS-SD style SRV and TXT lookup is executed. If only two
-        parameters are specified, the first is assumed to be the SRV service type, and the second the domain to look in. In
-        this case no TXT RR is requested. Finally, if only one parameter is specified, it is assumed to be a domain name,
-        that is already prefixed with an SRV type, and an SRV lookup is done (no TXT).</para></listitem>
+        <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>
       </varlistentry>
 
       <varlistentry>
         <term><command>openpgp</command> <replaceable>EMAIL@DOMAIN</replaceable>…</term>
 
-        <listitem><para>Query PGP keys stored as <ulink url="https://tools.ietf.org/html/rfc7929">OPENPGPKEY</ulink>
-        resource records. Specified e-mail addresses are converted to the corresponding DNS domain name, and any
-        OPENPGPKEY keys are printed.</para></listitem>
+        <listitem><para>Query PGP keys stored as <constant class='dns'>OPENPGPKEY</constant> resource records,
+        ssee <ulink url="https://tools.ietf.org/html/rfc7929">RFC 7929</ulink>. Specified e-mail addresses
+        are converted to the corresponding DNS domain name, and any <constant class='dns'>OPENPGPKEY</constant>
+        keys are printed.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -97,11 +102,13 @@
         [<replaceable>FAMILY</replaceable>]
         <replaceable>DOMAIN</replaceable>[:<replaceable>PORT</replaceable>]…</term>
 
-        <listitem><para>Query TLS public keys stored as <ulink url="https://tools.ietf.org/html/rfc6698">TLSA</ulink>
-        resource records. A query will be performed for each of the specified names prefixed with the port and family
+        <listitem><para>Query TLS public keys stored as <constant class='dns'>TLSA</constant> resource
+        records, see <ulink url="https://tools.ietf.org/html/rfc6698">RFC 6698</ulink>. A query will be
+        performed for each of the specified names prefixed with the port and family
         (<literal>_<replaceable>port</replaceable>._<replaceable>family</replaceable>.<replaceable>domain</replaceable></literal>).
-        The port number may be specified after a colon (<literal>:</literal>), otherwise <constant>443</constant> will be used
-        by default. The family may be specified as the first argument, otherwise <constant>tcp</constant> will be used.</para></listitem>
+        The port number may be specified after a colon (<literal>:</literal>), otherwise
+        <constant>443</constant> will be used by default. The family may be specified as the first argument,
+        otherwise <constant>tcp</constant> will be used.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -128,8 +135,8 @@
       <varlistentry>
         <term><command>flush-caches</command></term>
 
-        <listitem><para>Flushes all DNS resource record caches the service maintains locally. This is mostly equivalent
-        to sending the <constant>SIGUSR2</constant> to the <command>systemd-resolved</command>
+        <listitem><para>Flushes all DNS resource record caches the service maintains locally. This is mostly
+        equivalent to sending the <constant>SIGUSR2</constant> to the <command>systemd-resolved</command>
         service.</para></listitem>
       </varlistentry>
 
@@ -246,10 +253,11 @@
         <term><option>--class=</option><replaceable>CLASS</replaceable></term>
 
         <listitem><para>When used in conjunction with the <command>query</command> command, specifies the DNS
-        resource record type (e.g. A, AAAA, MX, …) and class (e.g. IN, ANY, …) to look up. If these options
-        are used a DNS resource record set matching the specified class and type is requested. The class
-        defaults to IN if only a type is specified. The special value <literal>help</literal> may be used to
-        list known values.</para>
+        resource record type (e.g. <constant class='dns'>A</constant>, <constant class='dns'>AAAA</constant>,
+        <constant class='dns'>MX</constant>, …) and class (e.g. <constant>IN</constant>,
+        <constant>ANY</constant>, …) to look up. If these options are used a DNS resource record set matching
+        the specified class and type is requested. The class defaults to <constant>IN</constant> if only a
+        type is specified. The special value <literal>help</literal> may be used to list known values.</para>
 
         <para>Without these options <command>resolvectl query</command> provides high-level domain name to
         address and address to domain name resolution. With these options it provides low-level DNS resource
@@ -264,20 +272,23 @@
         <term><option>--service-address=</option><replaceable>BOOL</replaceable></term>
 
         <listitem><para>Takes a boolean parameter. If true (the default), when doing a service lookup with
-        <option>--service</option> the hostnames contained in the SRV resource records are resolved as well.</para></listitem>
+        <option>--service</option> the hostnames contained in the <constant class='dns'>SRV</constant>
+        resource records are resolved as well.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><option>--service-txt=</option><replaceable>BOOL</replaceable></term>
 
-        <listitem><para>Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup with
-        <option>--service</option> the TXT service metadata record is resolved as well.</para></listitem>
+        <listitem><para>Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup
+        with <option>--service</option> the <constant class='dns'>TXT</constant> service metadata record is
+        resolved as well.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><option>--cname=</option><replaceable>BOOL</replaceable></term>
 
-        <listitem><para>Takes a boolean parameter. If true (the default), DNS CNAME or DNAME redirections are
+        <listitem><para>Takes a boolean parameter. If true (the default), DNS <constant
+        class='dns'>CNAME</constant> or <constant class='dns'>DNAME</constant> redirections are
         followed. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is
         returned.</para></listitem>
       </varlistentry>
@@ -465,7 +476,7 @@
     <title>Examples</title>
 
     <example>
-      <title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain</title>
+      <title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain (<constant class='dns'>A</constant> and <constant class='dns'>AAAA</constant> resource records)</title>
 
       <programlisting>$ resolvectl query www.0pointer.net
 www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74
@@ -477,7 +488,8 @@ www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74
     </example>
 
     <example>
-      <title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address</title>
+      <title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address
+      (<constant class='dns'>PTR</constant> resource record)</title>
 
       <programlisting>$ resolvectl query 85.214.157.71
 85.214.157.71: gardel.0pointer.net
@@ -488,7 +500,8 @@ www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74
     </example>
 
     <example>
-      <title>Retrieve the MX record of the <literal>yahoo.com</literal> domain</title>
+      <title>Retrieve the <constant class='dns'>MX</constant> record of the <literal>yahoo.com</literal>
+      domain</title>
 
       <programlisting>$ resolvectl --legend=no -t MX query yahoo.com
 yahoo.com. IN MX    1 mta7.am0.yahoodns.net
@@ -498,7 +511,7 @@ yahoo.com. IN MX    1 mta5.am0.yahoodns.net
     </example>
 
     <example>
-      <title>Resolve an SRV service</title>
+      <title>Resolve an <constant class='dns'>SRV</constant> service</title>
 
       <programlisting>$ resolvectl service _xmpp-server._tcp gmail.com
 _xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0]
@@ -510,7 +523,7 @@ _xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, we
     </example>
 
     <example>
-      <title>Retrieve a PGP key</title>
+      <title>Retrieve a PGP key (<constant class='dns'>OPENPGP</constant> resource record)</title>
 
       <programlisting>$ resolvectl openpgp zbyszek@fedoraproject.org
 d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY
@@ -521,8 +534,7 @@ d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproje
     </example>
 
     <example>
-      <title>Retrieve a TLS key (<literal>tcp</literal> and
-      <literal>:443</literal> could be skipped)</title>
+      <title>Retrieve a TLS key (<constant class='dns'>TLSA</constant> resource record)</title>
 
       <programlisting>$ resolvectl tlsa tcp fedoraproject.org:443
 _443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0
@@ -530,6 +542,8 @@ _443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0
         -- Selector: Full Certificate
         -- Matching type: SHA-256
 </programlisting>
+
+      <para><literal>tcp</literal> and <literal>:443</literal> are optional and could be skipped.</para>
     </example>
   </refsect1>
 
diff --git a/man/systemd.dnssd.xml b/man/systemd.dnssd.xml
index be2e873efb..c7d781b568 100644
--- a/man/systemd.dnssd.xml
+++ b/man/systemd.dnssd.xml
@@ -123,13 +123,15 @@
         <varlistentry>
           <term><varname>Priority=</varname></term>
           <listitem>
-            <para>A priority number set in SRV resource records corresponding to the network service.</para>
+            <para>A priority number set in <constant class='dns'>SRV</constant> resource records corresponding
+            to the network service.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term><varname>Weight=</varname></term>
           <listitem>
-            <para>A weight number set in SRV resource records corresponding to the network service.</para>
+            <para>A weight number set in <constant class='dns'>SRV</constant> resource records corresponding
+            to the network service.</para>
           </listitem>
         </varlistentry>
         <varlistentry>