doc: fixup more broken xrefs

Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>

doc/user/appendix.rst

@@ -3,10 +3,7 @@
 Packet Binary Dump Format
 =========================
 
-Packet Binary Dump Format
+FRR can dump routing protocol packets into a file with a binary format.
--------------------------
-
-FRR can dump routing protocol packet into file with a binary format.
 
 It seems to be better that we share the MRT's header format for
 backward compatibility with MRT's dump logs. We should also define the
@@ -211,12 +208,13 @@ The file specified in "File Name" contains all routing entries,
 which are in the format of ``subtype == BGP4MP_ENTRY``.
 
 ::
+
    Constants:
 
-     /* type value */
+     /\* type value \*/
      #define MSG_PROTOCOL_BGP4MP    16
      #define MSG_PROTOCOL_BGP4MP_ET 17
-     /* subtype value */
+     /\* subtype value \*/
      #define BGP4MP_STATE_CHANGE 0
      #define BGP4MP_MESSAGE 1
      #define BGP4MP_ENTRY 2

doc/user/isisd.rst

@@ -39,12 +39,10 @@ writing, *isisd* does not support multiple ISIS processes.
 .. index:: no router isis WORD
 .. clicmd:: no router isis WORD
 
-   .. _router-isis-word:
-
    Enable or disable the ISIS process by specifying the ISIS domain with
    'WORD'.  *isisd* does not yet support multiple ISIS processes but you must
    specify the name of ISIS process. The ISIS process name 'WORD' is then used
-   for interface (see command :ref:`ip-router-isis-word`).
+   for interface (see command :clicmd:`ip router isis WORD`).
 
 .. index:: net XX.XXXX. ... .XXX.XX
 .. clicmd:: net XX.XXXX. ... .XXX.XX
@@ -91,8 +89,6 @@ writing, *isisd* does not support multiple ISIS processes.
 .. index:: no metric-style
 .. clicmd:: no metric-style
 
-.. _metric-style:
-
    Set old-style (ISO 10589) or new-style packet formats:
 
    - narrow
@@ -203,7 +199,7 @@ ISIS interface
 
    Activate ISIS adjacency on this interface. Note that the name
    of ISIS instance must be the same as the one used to configure the ISIS process
-   (see command :ref:`router-isis-word`).
+   (see command :clicmd:`router isis WORD`).
 
 .. index:: isis circuit-type [level-1 | level-1-2 | level-2]
 .. clicmd:: isis circuit-type [level-1 | level-1-2 | level-2]
@@ -284,7 +280,7 @@ ISIS interface
 
    Set default metric value globally, for an area (level-1) or a domain
    (level-2).  Max value depend if metric support narrow or wide value (see
-   command :ref:`metric-style`).
+   command :clicmd:`metric-style [narrow | transition | wide]`).
 
 .. index:: isis network point-to-point
 .. clicmd:: isis network point-to-point

doc/user/ospf_fundamentals.rst

@@ -121,10 +121,8 @@ OSPF defines several related mechanisms, used to manage synchronisation of
 :abbr:`LSDB` s between neighbours as neighbours form adjacencies and the
 propogation, or :term:`flooding` of new or updated :abbr:`LSA` s.
 
-:ref:`ospf-flooding`.
-
-
 .. index:: OSPF Areas overview
+
 .. _ospf-areas:
 
 Areas
@@ -174,7 +172,11 @@ All LSAs share a common header with the following information:
 
 - Advertising Router
 
-  The Router ID of the router originating the LSA, see :ref:`ospf-router-id`.
+  The Router ID of the router originating the LSA.
+
+.. seealso::
+
+   :clicmd:`ospf router-id A.B.C.D`.
 
 - LSA ID
 
@@ -186,7 +188,7 @@ All LSAs share a common header with the following information:
   The combination of the Type, ID and Advertising Router ID must uniquely
   identify the :abbr:`LSA`. There can however be multiple instances of
   an LSA with the same Type, LSA ID and Advertising Router ID, see
-  :ref:`ospf-lsa-sequence-number,,lsa-sequence-number`.
+  :ref:`Sequence Number <ospf-lsa-sequence-number>`.
 
 - Age
 
@@ -206,7 +208,7 @@ All LSAs share a common header with the following information:
   a router has shutdown without flushing its LSA(s), e.g. where it has
   become disconnected from the network. Such LSAs do little harm.
 
-  .. _ospf-lsa-sequence-number:
+.. _ospf-lsa-sequence-number:
 
 - Sequence Number
 
@@ -232,7 +234,7 @@ called :term:`intra-area routes`.
 
   Cost
      The output cost of that interface, scaled inversely to some commonly known
-     reference value, :ref:`ospf-auto-cost-reference-bandwidth,,auto-cost-reference-bandwidth`.
+     reference value, :clicmd:`auto-cost reference-bandwidth (1-4294967`.
 
   Link Type
      Transit Network
@@ -272,7 +274,7 @@ called :term:`intra-area routes`.
 
     Stub links may also be used as a way to describe links on which OSPF is
     *not* spoken, known as :term:`passive interfaces`, see
-    :ref:`ospf-passive-interface,,passive-interface`.
+    :clicmd:`passive-interface INTERFACE`.
 
 - Network LSA
 

doc/user/ospfd.rst

@@ -51,8 +51,6 @@ writing, *ospfd* does not support multiple OSPF processes.
 .. index:: no ospf router-id
 .. clicmd:: no ospf router-id
 
-.. _ospf-router-id:
-
    This sets the router-ID of the OSPF process. The
    router-ID may be an IP address of the router, but need not be - it can
    be any arbitrary 32bit number. However it MUST be unique within the
@@ -67,36 +65,36 @@ writing, *ospfd* does not support multiple OSPF processes.
 .. index:: no ospf abr-type TYPE
 .. clicmd:: no ospf abr-type TYPE
 
-  `type` can be cisco|ibm|shortcut|standard. The "Cisco" and "IBM" types
+   `type` can be cisco|ibm|shortcut|standard. The "Cisco" and "IBM" types
-  are equivalent.
+   are equivalent.
 
-  The OSPF standard for ABR behaviour does not allow an ABR to consider
+   The OSPF standard for ABR behaviour does not allow an ABR to consider
-  routes through non-backbone areas when its links to the backbone are
+   routes through non-backbone areas when its links to the backbone are
-  down, even when there are other ABRs in attached non-backbone areas
+   down, even when there are other ABRs in attached non-backbone areas
-  which still can reach the backbone - this restriction exists primarily
+   which still can reach the backbone - this restriction exists primarily
-  to ensure routing-loops are avoided.
+   to ensure routing-loops are avoided.
 
-  With the "Cisco" or "IBM" ABR type, the default in this release of
+   With the "Cisco" or "IBM" ABR type, the default in this release of
-  FRR, this restriction is lifted, allowing an ABR to consider
+   FRR, this restriction is lifted, allowing an ABR to consider
-  summaries learnt from other ABRs through non-backbone areas, and hence
+   summaries learnt from other ABRs through non-backbone areas, and hence
-  route via non-backbone areas as a last resort when, and only when,
+   route via non-backbone areas as a last resort when, and only when,
-  backbone links are down.
+   backbone links are down.
 
-  Note that areas with fully-adjacent virtual-links are considered to be
+   Note that areas with fully-adjacent virtual-links are considered to be
-  "transit capable" and can always be used to route backbone traffic, and
+   "transit capable" and can always be used to route backbone traffic, and
-  hence are unaffected by this setting (:ref:`ospf-virtual-link`).
+   hence are unaffected by this setting (:clicmd:`area A.B.C.D virtual-link A.B.C.D`).
 
-  More information regarding the behaviour controlled by this command can
+   More information regarding the behaviour controlled by this command can
-  be found in :rfc:`3509`, and :t:`draft-ietf-ospf-shortcut-abr-02.txt`.
+   be found in :rfc:`3509`, and :t:`draft-ietf-ospf-shortcut-abr-02.txt`.
 
-  Quote: "Though the definition of the :abbr:`ABR (Area Border Router)`
+   Quote: "Though the definition of the :abbr:`ABR (Area Border Router)`
-  in the OSPF specification does not require a router with multiple
+   in the OSPF specification does not require a router with multiple
-  attached areas to have a backbone connection, it is actually
+   attached areas to have a backbone connection, it is actually
-  necessary to provide successful routing to the inter-area and
+   necessary to provide successful routing to the inter-area and
-  external destinations. If this requirement is not met, all traffic
+   external destinations. If this requirement is not met, all traffic
-  destined for the areas not connected to such an ABR or out of the
+   destined for the areas not connected to such an ABR or out of the
-  OSPF domain, is dropped. This document describes alternative ABR
+   OSPF domain, is dropped. This document describes alternative ABR
-  behaviors implemented in Cisco and IBM routers."
+   behaviors implemented in Cisco and IBM routers."
 
 .. index:: ospf rfc1583compatibility
 .. clicmd:: ospf rfc1583compatibility
@@ -129,16 +127,14 @@ writing, *ospfd* does not support multiple OSPF processes.
 .. index:: no passive-interface INTERFACE
 .. clicmd:: no passive-interface INTERFACE
 
-.. _ospf-passive-interface:
+   Do not speak OSPF interface on the
-
+   given interface, but do advertise the interface as a stub link in the
-    Do not speak OSPF interface on the
+   router-:abbr:`LSA (Link State Advertisement)` for this router. This
-    given interface, but do advertise the interface as a stub link in the
+   allows one to advertise addresses on such connected interfaces without
-    router-:abbr:`LSA (Link State Advertisement)` for this router. This
+   having to originate AS-External/Type-5 LSAs (which have global flooding
-    allows one to advertise addresses on such connected interfaces without
+   scope) - as would occur if connected addresses were redistributed into
-    having to originate AS-External/Type-5 LSAs (which have global flooding
+   OSPF (:ref:`redistribute-routes-to-ospf`). This is the only way to
-    scope) - as would occur if connected addresses were redistributed into
+   advertise non-OSPF links into stub areas.
-    OSPF (:ref:`redistribute-routes-to-ospf`). This is the only way to
-    advertise non-OSPF links into stub areas.
 
 .. index:: timers throttle spf DELAY INITIAL-HOLDTIME MAX-HOLDTIME
 .. clicmd:: timers throttle spf DELAY INITIAL-HOLDTIME MAX-HOLDTIME
@@ -164,7 +160,7 @@ writing, *ospfd* does not support multiple OSPF processes.
    by the `maximum-holdtime` configured with this command. If the adaptive
    hold-time elapses without any SPF-triggering event occuring then
    the current holdtime is reset to the `initial-holdtime`. The current
-   holdtime can be viewed with :ref:`show-ip-ospf`, where it is expressed as
+   holdtime can be viewed with :clicmd:`show ip ospf`, where it is expressed as
    a multiplier of the `initial-holdtime`.
 
    ::
@@ -218,7 +214,7 @@ writing, *ospfd* does not support multiple OSPF processes.
 
    Configured state of this feature as well as current status, such as the
    number of second remaining till on-startup or on-shutdown ends, can be
-   viewed with the :ref:`show-ip-ospf` command.
+   viewed with the :clicmd:`show ip ospf` command.
 
 .. index:: auto-cost reference-bandwidth (1-4294967)
 .. clicmd:: auto-cost reference-bandwidth (1-4294967)
@@ -226,8 +222,6 @@ writing, *ospfd* does not support multiple OSPF processes.
 .. index:: no auto-cost reference-bandwidth
 .. clicmd:: no auto-cost reference-bandwidth
 
-.. _OSPF-auto-cost-reference-bandwidth:
-
    This sets the reference
    bandwidth for cost calculations, where this bandwidth is considered
    equivalent to an OSPF cost of 1, specified in Mbits/s. The default is
@@ -250,8 +244,6 @@ writing, *ospfd* does not support multiple OSPF processes.
 .. index:: no network A.B.C.D/M area (0-4294967295)
 .. clicmd:: no network A.B.C.D/M area (0-4294967295)
 
-.. _ospf-network-command:
-
    This command specifies the OSPF enabled interface(s). If the interface has
    an address from range 192.168.1.0/24 then the command below enables ospf
    on this interface so router can provide network information to the other
@@ -276,7 +268,7 @@ writing, *ospfd* does not support multiple OSPF processes.
    contains the local address prefix of the interface.
 
    In some cases it may be more convenient to enable OSPF on a per
-   interface/subnet basis (:ref:`ospf-ip-ospf-area-command`).
+   interface/subnet basis (:clicmd:`ip ospf area AREA [ADDR]`).
 
 
 .. _ospf-area:
@@ -357,8 +349,6 @@ OSPF area
 .. index:: no area (0-4294967295) virtual-link A.B.C.D
 .. clicmd:: no area (0-4294967295) virtual-link A.B.C.D
 
-.. _OSPF-virtual-link:
-
 .. index:: area A.B.C.D shortcut
 .. clicmd:: area A.B.C.D shortcut
 
@@ -513,15 +503,13 @@ OSPF area
 .. index:: area (0-4294967295) authentication message-digest
 .. clicmd:: area (0-4294967295) authentication message-digest
 
-.. _area-authentication-message-digest:
+   Specify that OSPF packets must be authenticated with MD5 HMACs within the
+   given area. Keying material must also be configured on a per-interface basis
+   (:clicmd:`ip ospf message-digest-key`).
 
-      Specify that OSPF packets
+   MD5 authentication may also be configured on a per-interface basis
-      must be authenticated with MD5 HMACs within the given area. Keying
+   (:clicmd:`ip ospf authentication message-digest`). Such per-interface
-      material must also be configured on a per-interface basis (:ref:`ip-ospf-message-digest-key`).
+   settings will override any per-area authentication setting.
-
-      MD5 authentication may also be configured on a per-interface basis
-      (:ref:`ip-ospf-authentication-message-digest`). Such per-interface
-      settings will override any per-area authentication setting.
 
 .. _ospf-interface:
 
@@ -534,11 +522,10 @@ OSPF interface
 .. index:: no ip ospf area [ADDR]
 .. clicmd:: no ip ospf area [ADDR]
 
-.. _ospf-ip-ospf-area-command:
-
    Enable OSPF on the interface, optionally restricted to just the IP address
-   given by `ADDR`, putting it in the `AREA` area. Per interface area
+   given by `ADDR`, putting it in the `AREA` area. Per interface area settings
-   settings take precedence to network commands (:ref:`ospf-network-command`).
+   take precedence to network commands
+   (:clicmd:`network A.B.C.D/M area A.B.C.D`).
 
    If you have a lot of interfaces, and/or a lot of subnets, then enabling OSPF
    via this command may result in a slight performance improvement.
@@ -553,26 +540,24 @@ OSPF interface
    all OSPF packets are authenticated. `AUTH_KEY` has length up to 8 chars.
 
    Simple text password authentication is insecure and deprecated in favour of
-   MD5 HMAC authentication (:ref:`ip-ospf-authentication-message-digest`).
+   MD5 HMAC authentication.
 
 .. index:: ip ospf authentication message-digest
 .. clicmd:: ip ospf authentication message-digest
 
-.. _ip-ospf-authentication-message-digest:
+   Specify that MD5 HMAC authentication must be used on this interface. MD5
-
+   keying material must also be configured. Overrides any authentication
-   Specify that MD5 HMAC
+   enabled on a per-area basis
-   authentication must be used on this interface. MD5 keying material must
+   (:clicmd:`area A.B.C.D authentication message-digest`)
-   also be configured (:ref:`ip-ospf-message-digest-key`). Overrides any
-   authentication enabled on a per-area basis (:ref:`area-authentication-message-digest`).
 
    Note that OSPF MD5 authentication requires that time never go backwards
    (correct time is NOT important, only that it never goes backwards), even
    across resets, if ospfd is to be able to promptly reestabish adjacencies
-   with its neighbours after restarts/reboots. The host should have system
+   with its neighbours after restarts/reboots. The host should have system time
-   time be set at boot from an external or non-volatile source (eg battery backed clock, NTP,
+   be set at boot from an external or non-volatile source (eg battery backed
-   etc.) or else the system clock should be periodically saved to non-volative
+   clock, NTP, etc.) or else the system clock should be periodically saved to
-   storage and restored at boot if MD5 authentication is to be expected to work
+   non-volative storage and restored at boot if MD5 authentication is to be
-   reliably.
+   expected to work reliably.
 
 .. index:: ip ospf message-digest-key KEYID md5 KEY
 .. clicmd:: ip ospf message-digest-key KEYID md5 KEY
@@ -580,17 +565,15 @@ OSPF interface
 .. index:: no ip ospf message-digest-key
 .. clicmd:: no ip ospf message-digest-key
 
-.. _ip-ospf-message-digest-key:
+   Set OSPF authentication key to a cryptographic password. The cryptographic
+   algorithm is MD5.
 
-  Set OSPF authentication key to a
+   KEYID identifies secret key used to create the message digest. This ID
-  cryptographic password. The cryptographic algorithm is MD5.
+   is part of the protocol and must be consistent across routers on a
+   link.
 
-  KEYID identifies secret key used to create the message digest. This ID
+   KEY is the actual message digest key, of up to 16 chars (larger strings
-  is part of the protocol and must be consistent across routers on a
+   will be truncated), and is associated with the given KEYID.
-  link.
-
-  KEY is the actual message digest key, of up to 16 chars (larger strings
-  will be truncated), and is associated with the given KEYID.
 
 .. index:: ip ospf cost (1-65535)
 .. clicmd:: ip ospf cost (1-65535)
@@ -610,21 +593,18 @@ OSPF interface
 .. index:: no ip ospf dead-interval
 .. clicmd:: no ip ospf dead-interval
 
-.. _ip-ospf-dead-interval-minimal:
+   Set number of seconds for RouterDeadInterval timer value used for Wait Timer
+   and Inactivity Timer. This value must be the same for all routers attached
+   to a common network. The default value is 40 seconds.
 
-    Set number of seconds for
+   If 'minimal' is specified instead, then the dead-interval is set to 1 second
-    RouterDeadInterval timer value used for Wait Timer and Inactivity
+   and one must specify a hello-multiplier. The hello-multiplier specifies how
-    Timer. This value must be the same for all routers attached to a
+   many Hellos to send per second, from 2 (every 500ms) to 20 (every 50ms).
-    common network. The default value is 40 seconds.
+   Thus one can have 1s convergence time for OSPF. If this form is specified,
-
+   then the hello-interval advertised in Hello packets is set to 0 and the
-    If 'minimal' is specified instead, then the dead-interval is set to 1
+   hello-interval on received Hello packets is not checked, thus the
-    second and one must specify a hello-multiplier. The hello-multiplier
+   hello-multiplier need NOT be the same across multiple routers on a common
-    specifies how many Hellos to send per second, from 2 (every 500ms) to
+   link.
-    20 (every 50ms). Thus one can have 1s convergence time for OSPF. If this form
-    is specified, then the hello-interval advertised in Hello packets is set to
-    0 and the hello-interval on received Hello packets is not checked, thus
-    the hello-multiplier need NOT be the same across multiple routers on a common
-    link.
 
 .. index:: ip ospf hello-interval (1-65535)
 .. clicmd:: ip ospf hello-interval (1-65535)
@@ -637,7 +617,8 @@ OSPF interface
    This value must be the same for all routers attached to a common network.
    The default value is 10 seconds.
 
-   This command has no effect if :ref:`ip-ospf-dead-interval-minimal` is also
+   This command has no effect if
+   :clicmd:`ip ospf dead-interval minimal hello-multiplier (2-20)` is also
    specified for the interface.
 
 .. index:: ip ospf network (broadcast|non-broadcast|point-to-multipoint|point-to-point)
@@ -725,7 +706,7 @@ Redistribute routes to OSPF
    or kind into OSPF, with the metric type and metric set if specified,
    filtering the routes using the given route-map if specified.
    Redistributed routes may also be filtered with distribute-lists, see
-   :ref:`ospf-distribute-list`.
+   :ref:`OSPF distribute-list configuration <ospf-distribute-list>`.
 
    Redistributed routes are distributed as into OSPF as Type-5 External
    LSAs into links to areas that accept external routes, Type-7 External LSAs
@@ -733,7 +714,11 @@ Redistribute routes to OSPF
    external routes are not permitted.
 
    Note that for connected routes, one may instead use
-   :term:`passive-interface`, see :ref:`ospf-passive-interface`.
+   :term:`passive-interface`;
+
+.. seealso::
+
+   clicmd:`passive-interface INTERFACE`.
 
 .. index:: default-information originate
 .. clicmd:: default-information originate
@@ -777,7 +762,7 @@ Redistribute routes to OSPF
 
     Apply the access-list filter, NAME, to
     redistributed routes of the given type before allowing the routes to
-    redistributed into OSPF (:ref:`ospf-redistribute`).
+    redistributed into OSPF (:ref:`OSPF redistribution <ospf-redistribute>`).
 
 .. index:: default-metric (0-16777214)
 .. clicmd:: default-metric (0-16777214)

doc/user/protocol.rst

@@ -1,4 +1,4 @@
-.. _Zebra-Protocol
+.. _Zebra-Protocol:
 
 **************
 Zebra Protocol

doc/user/routeserver.rst

@@ -43,6 +43,7 @@ it consists of three steps:
   accepted by the `Out` filters of a peer are announced to that peer.
 
 .. _fig-normal-processing:
+
 .. figure:: ../figures/fig-normal-processing.png
    :alt: Normal announcement processing
    :align: center
@@ -50,6 +51,7 @@ it consists of three steps:
    Announcement processing inside a 'normal' BGP speaker
 
 .. _fig-topologies-full:
+
 .. figure:: ../figures/fig_topologies_full.png
    :alt: Full Mesh BGP Topology
    :align: center
@@ -57,6 +59,7 @@ it consists of three steps:
    Full Mesh
 
 .. _fig-topologies-rs:
+
 .. figure:: ../figures/fig_topologies_rs.png
    :alt: Route Server BGP Topology
    :align: center
@@ -69,6 +72,7 @@ having a single BGP peering (against the route server), the BGP speakers can no
 longer distinguish from/to which peer each announce comes/goes.
 
 .. _filter-delegation:
+
 This means that the routers connected to the route server are not able to apply
 by themselves the same input/output filters as in the full mesh scenario, so
 they have to delegate those functions to the route server.

doc/user/vnc.rst

@@ -56,8 +56,8 @@ following areas:
 
 .. _general-vnc-configuration:
 
-.. General VNC Configuration
+General VNC Configuration
-.. -------------------------
+-------------------------
 
 .. _rfp-related-configuration:
 
@@ -246,7 +246,7 @@ Defaults section.
    - ``IPv4-address:two-byte-integer``
    - ``four-byte-autonomous-system-number:two-byte-integer``
    - ``two-byte-autonomous-system-number:four-byte-integer``
-   - ``auto:vn:`two-byte-integer`
+   - ``auto:vn:two-byte-integer``
 
    Routes originated by NVEs in the NVE group will use the group's specified
    `route-distinguisher` when they are advertised via BGP.  If the `auto` form
@@ -902,7 +902,7 @@ Mesh NVA Configuration
 
 This example includes three NVAs, nine NVEs, and two NVE groups. Note that
 while not shown, a single physical device may support multiple logical NVEs.
-:ref:`fig-vnc-mesh` shows ``code NVA-1`` (192.168.1.100), ``NVA 2``
+:ref:`vnc-fig-vnc-mesh` shows ``code NVA-1`` (192.168.1.100), ``NVA 2``
 (192.168.1.101), and ``NVA 3`` (192.168.1.102), which are connected in a full
 mesh. Each is a member of the autonomous system 64512. Each NVA provides VNC
 services to three NVE clients in the 172.16.0.0/16 virtual-network address
@@ -918,6 +918,7 @@ Each NVA advertises NVE underlay-network IP addresses using the
 Tunnel Encapsulation Attribute.
 
 .. _vnc-fig-vnc-mesh:
+
 .. figure:: ../figures/fig-vnc-mesh.png
    :align: center
    :alt: Three-way Mesh
@@ -1229,7 +1230,7 @@ While not shown, an NVA can also be configured as a route reflector.
 VNC with Commercial Route Reflector Configuration
 -------------------------------------------------
 
-This example is identical to :ref:`vnc-with-frr-route-reflector-configuration`
+This example is identical to :ref:`vnc-with-frr-route-reflector-config`
 with the exception that the route reflector is a commercial router. Only the
 VNC-relevant configuration is provided.