Add link anchor and hyperlinks to keys statement

This is super confusing because statement "keys" exists in context
controls and server blocks where it refers to symmetric TSIG key, and it
_also_ exists in dnssec-policy block where it specifies public-private
key pair parameters.

In an (unsuccessful) attempt to disambiguate these two I added bunch of
hyperlinks and a warning.

diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst
index 58bf7f217fbd9660a13f77cf5f28344e4f7a5242..941887cf1ac305990bd120bbc6ddd2371f4dda15 100644 (file)
--- a/doc/arm/reference.rst
+++ b/doc/arm/reference.rst
@@ -313,10 +313,12 @@ file documentation:
         When specifying a prefix involving an IPv6-scoped address, the scope may be omitted. In that case, the prefix matches packets from any scope.
 
     ``key_id``
-        A ``domain_name`` representing the name of a shared key, to be used for transaction security.
+        A ``domain_name`` representing the name of a shared key, to be used for
+        :ref:`transaction security <tsig>`. Keys are defined using
+        :namedconf:ref:`key` blocks.
 
     ``key_list``
-        A list of one or more ``key_id``, separated by semicolons and ending with a semicolon.
+        A list of one or more :term:`key_id` s, separated by semicolons and ending with a semicolon.
 
     ``tls_id``
         A string representing a TLS configuration object, including a key and certificate.
@@ -500,8 +502,8 @@ and retrieve non-DNS results from a name server.
 
    ``keys``
       The primary authorization mechanism of the command channel is the
-      ``key_list``, which contains a list of ``key_id``s. Each ``key_id`` in
-      the ``key_list`` is authorized to execute commands over the control
+      :term:`key_list`, which contains a list of :term:`key_id` s. Each
+      :namedconf:ref:`key` is authorized to execute commands over the control
       channel. See :ref:`admin_tools` for information about
       configuring keys in :iscman:`rndc`.
 
@@ -5277,9 +5279,17 @@ any top-level ``server`` statements are used as defaults.
    specified, the limit is set according to the ``transfers-per-ns``
    option.
 
-``keys``
-   The option identifies a ``key_id`` defined by the ``key``
-   statement, to be used for transaction security (see :ref:`tsig`)
+.. namedconf:statement:: keys
+   :suppress_grammar:
+
+   .. warning::
+      Not to be confused with ``keys`` in :any:`dnssec-policy` specification.
+      Although statements with the same name exist in both contexts, they refer
+      to fundamentally incompatible concepts.
+
+   In the context of a :namedconf:ref:`server` block, the option identifies a
+   :term:`key_id` defined by the :namedconf:ref:`key` statement, to be used for
+   transaction security (see :ref:`tsig`)
    when talking to the remote server. When a request is sent to the remote
    server, a request signature is generated using the key specified
    here and appended to the message. A request originating from the remote
@@ -6093,8 +6103,9 @@ run multiple servers.
    ``address_match_list`` of the view's ``match-destinations`` clause. If
    not specified, both ``match-clients`` and ``match-destinations`` default
    to matching all addresses. In addition to checking IP addresses,
-   ``match-clients`` and ``match-destinations`` can also take ``keys``
-   which provide an mechanism for the client to select the view.
+   ``match-clients`` and ``match-destinations`` can also take the name of a
+   TSIG :namedconf:ref:`key`, which provides a mechanism for the client to select
+   the view.
 
 .. namedconf:statement:: match-recursive-only