7 files changed, 42 insertions, 36 deletions
diff --git a/docs/routing/index.rst b/docs/routing/index.rst
index a34bbfac..7988b230 100644
--- a/docs/routing/index.rst
+++ b/docs/routing/index.rst
@@ -16,6 +16,6 @@ Routing
    ospf
    pbr
    rip
-   routing-policy
+   policy
    rpki
    static
diff --git a/docs/routing/mss-clamp.rst b/docs/routing/mss-clamp.rst
index a4edf1c6..3fdd1153 100644
--- a/docs/routing/mss-clamp.rst
+++ b/docs/routing/mss-clamp.rst
@@ -1,7 +1,8 @@
 .. _routing-mss-clamp:
 
+################
 TCP-MSS Clamping
-----------------
+################
 
 As Internet wide PMTU discovery rarely works, we sometimes need to clamp
 our TCP MSS value to a specific value. This is a field in the TCP
@@ -18,16 +19,15 @@ value for IPv4 and IPv6.
 
 
 IPv4
-^^^^
+====
 
 .. cfgcmd:: set firewall options interface <interface> adjust-mss <number-of-bytes>
 
    Use this command to set the maximum segment size for IPv4 transit
    packets on a specific interface (500-1460 bytes).
 
-
 Example
-"""""""
+-------
 
 Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and
 `1372`
@@ -39,16 +39,15 @@ for your WireGuard `wg02` tunnel.
   set firewall options interface wg02 adjust-mss '1372'
 
 IPv6
-^^^^^
+====
 
 .. cfgcmd:: set firewall options interface <interface> adjust-mss6 <number-of-bytes>
 
    Use this command to set the maximum segment size for IPv6 transit
    packets on a specific interface (1280-1492 bytes).
 
-
 Example
-"""""""
+-------
 
 Clamp outgoing MSS value in a TCP SYN packet to `1280` for both `pppoe0` and
 `wg02` interface.
diff --git a/docs/routing/multicast.rst b/docs/routing/multicast.rst
index d20d8e31..9104b0c9 100644
--- a/docs/routing/multicast.rst
+++ b/docs/routing/multicast.rst
@@ -7,7 +7,6 @@ Multicast
 VyOS facilitates IP Multicast by supporting **PIM Sparse Mode**,
 **IGMP** and **IGMP-Proxy**.
 
-
 ************
 PIM and IGMP
 ************
@@ -16,7 +15,7 @@ PIM (Protocol Independent Multicast) must be configured in every
 interface of every participating router. Every router must also have the
 location of the Rendevouz Point manually configured. Then,
 unidirectional shared trees rooted at the Rendevouz Point will
-automatically be built for multicast distribution. 
+automatically be built for multicast distribution.
 
 Traffic from multicast sources will go to the Rendezvous Point, and
 receivers will pull it from a shared tree using IGMP (Internet Group
@@ -24,7 +23,7 @@ Management Protocol).
 
 Multicast receivers will talk IGMP to their local router, so, besides
 having PIM configured in every router, IGMP must also be configured in
-any router where there could be a multicast receiver locally connected. 
+any router where there could be a multicast receiver locally connected.
 
 VyOS supports both IGMP version 2 and version 3 (which allows
 source-specific multicast).
@@ -54,7 +53,7 @@ In the following example we can see a basic multicast setup:
    set protocols pim interface eth1
    set protocols pim interface eth2
    set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
-   
+
 **Router 3**
 
 .. code-block:: none
@@ -69,7 +68,7 @@ In the following example we can see a basic multicast setup:
    set protocols pim interface eth0
    set protocols pim interface eth1
    set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
-   
+
 **Router 2**
 
 .. code-block:: none
@@ -81,7 +80,7 @@ In the following example we can see a basic multicast setup:
    set protocols pim interface eth1
    set protocols pim interface eth2
    set protocols pim rp address 172.16.255.1 group '224.0.0.0/4'
-   
+
 
 
 
@@ -103,7 +102,7 @@ These are the commands for a basic setup.
    that join messages can be sent there. Set the Rendevouz Point address
    and the matching prefix of group ranges covered. These values must
    be shared with every router participating in the PIM network.
- 
+
 
 .. cfgcmd:: set protocols igmp interface eth1
 
@@ -163,7 +162,7 @@ You can also tune multicast with the following commands.
    timed out.
 
 
-.. cfgcmd:: set protocols igmp interface <interface> version <version-number> 
+.. cfgcmd:: set protocols igmp interface <interface> version <version-number>
 
    Use this command to define in the selected interface whether you
    choose IGMP version 2 or 3. The default value is 3.
diff --git a/docs/routing/ospf.rst b/docs/routing/ospf.rst
index fbe8984f..fe05178b 100644
--- a/docs/routing/ospf.rst
+++ b/docs/routing/ospf.rst
@@ -2,8 +2,9 @@
 
 .. _routing-ospf:
 
+####
 OSPF
-----
+####
 
 :abbr:`OSPF (Open Shortest Path First)` is a routing protocol for Internet
 Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls
@@ -16,7 +17,7 @@ addressing model.
 OSPF is a widely used IGP in large enterprise networks.
 
 OSPFv2 (IPv4)
-^^^^^^^^^^^^^
+#############
 
 In order to have a VyOS system exchanging routes with OSPF neighbors, you will
 at least need to configure an OSPF area and some network.
@@ -68,7 +69,7 @@ address and the node 1 sending the default route:
   set policy route-map CONNECT rule 10 match interface lo
 
 OSPFv3 (IPv6)
-^^^^^^^^^^^^^
+#############
 
 A typical configuration using 2 nodes.
 
diff --git a/docs/routing/pbr.rst b/docs/routing/pbr.rst
index 797f79e3..2a1a56bc 100644
--- a/docs/routing/pbr.rst
+++ b/docs/routing/pbr.rst
@@ -2,8 +2,9 @@
 
 .. _routing-pbr:
 
+###
 PBR
----
+###
 
 :abbr:`PBR (Policy-Based Routing)` allowing traffic to be assigned to
 different routing tables. Traffic can be matched using standard 5-tuple
@@ -11,7 +12,7 @@ matching (source address, destination address, protocol, source port,
 destination port).
 
 Transparent Proxy
-^^^^^^^^^^^^^^^^^
+=================
 
 The following example will show how VyOS can be used to redirect web
 traffic to an external transparent proxy:
@@ -45,7 +46,7 @@ interface, we use:
 
 
 Multiple Uplinks
-^^^^^^^^^^^^^^^^
+================
 
 VyOS Policy-Based Routing (PBR) works by matching source IP address
 ranges and forwarding the traffic using different routing tables.
diff --git a/docs/routing/routing-policy.rst b/docs/routing/policy.rst
index 461e42d8..4eeb40d6 100644
--- a/docs/routing/routing-policy.rst
+++ b/docs/routing/policy.rst
@@ -1,32 +1,35 @@
 .. include:: ../_include/need_improvement.txt
 
-Routing-policy
---------------
+######
+Policy
+######
 
-Routing Policies could be used to tell the router (self or neighbors) what routes and their attributes needs to be put into the routing table.
+Routing Policies could be used to tell the router (self or neighbors) what
+routes and their attributes needs to be put into the routing table.
 
 There could be a wide range of routing policies. Some examples are below:
 
-  * Set some metric to routes learned from a particular neighbor
-  * Set some attributes (like AS PATH or Community value) to advertised routes to neighbors
-  * Prefer a specific routing protocol routes over another routing protocol running on the same router
+* Set some metric to routes learned from a particular neighbor
+* Set some attributes (like AS PATH or Community value) to advertised routes to neighbors
+* Prefer a specific routing protocol routes over another routing protocol running on the same router
 
-Routing Policy Example
-~~~~~~~~~~~~~~~~~~~~~~
+Example
+=======
 
 **Policy definition:**
 
 .. code-block:: none
 
-  #Create policy
+  # Create policy
   set policy route-map setmet rule 2 action 'permit'
   set policy route-map setmet rule 2 set as-path-prepend '2 2 2'
 
-  #Apply policy to BGP
+  # Apply policy to BGP
   set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet'
-  set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' <<<< ***
+  set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound'
 
-  *** get policy update without bouncing the neighbor
+Using 'soft-reconfiguration' we get the policy update without bouncing the
+neighbor.
 
 **Routes learned before routing policy applied:**
 
@@ -54,7 +57,9 @@ Routing Policy Example
   Origin codes: i - IGP, e - EGP, ? - incomplete
 
      Network          Next Hop            Metric LocPrf Weight Path
-  *> 198.51.100.3/32   203.0.113.2           1             0 2 2 2 2 i < longer AS_path length
+  *> 198.51.100.3/32   203.0.113.2           1             0 2 2 2 2 i
 
   Total number of prefixes 1
   vyos@vos1:~$
+
+You now see the longer AS path.
diff --git a/docs/routing/rip.rst b/docs/routing/rip.rst
index 9cf4f289..68868e37 100644
--- a/docs/routing/rip.rst
+++ b/docs/routing/rip.rst
@@ -2,8 +2,9 @@
 
 .. _rip:
 
+###
 RIP
----
+###
 
 :abbr:`RIP (Routing Information Protocol)` is a widely deployed interior gateway
 protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS