Spelling, a few minor rewrites.

4 files changed, 23 insertions, 15 deletions

diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst
index 8ef002f8..075b3836 100644
--- a/docs/interfaces/ethernet.rst
+++ b/docs/interfaces/ethernet.rst
@@ -28,10 +28,12 @@ Resulting in:
       speed auto
   }
 
-In addition, Ethernet interfaces provide the extended operational commands
-`show interfaces ethernet <name> physical` and
-`show interfaces ethernet <name> statistics`. Statistics available are driver
-dependent.
+In addition, Ethernet interfaces provide the extended operational commands:
+
+* `show interfaces ethernet <name> physical`
+* `show interfaces ethernet <name> statistics` 
+
+Statistics available are driver dependent.
 
 .. code-block:: sh
 
diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst
index 883a3c5d..c4eb2d8f 100644
--- a/docs/interfaces/pppoe.rst
+++ b/docs/interfaces/pppoe.rst
@@ -8,8 +8,9 @@ There are two main ways to setup VyOS to connect over a PPPoE internet connectio
 
 **First Method:** (Common for Homes)
 
-In this method, the DSL Modem/Router connects to the DSL ISP for you with your credentials preprogrammed into the device and it gives you a local IP address such as 192.168.1.0/24 be default.
-For home networks this is usually fine and saves you trouble but if you want to run a configuration of your own controlled by VyOS, this would mean a Double Firewall, a Double NAT, and double Router as both the DSL Modem/Router and the VyOS would act as firewalls, NATs, and Routers and if you try to do more then just browse Web Sites this will usually cause you trouble.
+In this method, the DSL Modem/Router connects to the ISP for you with your credentials preprogrammed into the device.  This gives you an RFC1918_ address, such as 192.168.1.0/24 by default.
+
+For a simple home network using just the ISP's equipment, this is usually desirable.  But if you want to run VyOS as your firewall and router, this will result in having a double NAT and firewall setup. This results in a few extra layers of complexity, particularly if you use some NAT or tunnel features.
 
 **Second Method:** (Common for Businesses)
 
@@ -77,3 +78,5 @@ This command shows the same log as without the 'tail' option but only starts wit
 .. code-block:: sh
 
   show interfaces pppoe 0 log tail
+
+.. _RFC1918: https://tools.ietf.org/html/rfc1918
diff --git a/docs/interfaces/tunnel.rst b/docs/interfaces/tunnel.rst
index f466a714..7103e5a2 100644
--- a/docs/interfaces/tunnel.rst
+++ b/docs/interfaces/tunnel.rst
@@ -13,8 +13,8 @@ All those protocols are grouped under 'interfaces tunnel' in VyOS. Let's take a
 IPIP
 ----
 
-This is the simplest tunneling protocol in existence. It is defined by RFC2003_.
-It simply takes an IPv4 packet and sends it as a payload of another IPv4 packet. For this reason it doesn't really have any configuration options by itself.
+This is one of the simplest types of tunnels, as defined by RFC2003_.
+It takes an IPv4 packet and sends it as a payload of another IPv4 packet. For this reason, there are no other configuration options for this kind of tunnel.
 
 An example:
 
@@ -64,7 +64,7 @@ An example:
 6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in RFC4213_.
 The 6in4 traffic is sent over IPv4 inside IPv4 packets whose IP headers have the IP protocol number set to 41.
 This protocol number is specifically designated for IPv6 encapsulation, the IPv4 packet header is immediately followed by the IPv6 packet being carried.
-qThe encapsulation overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of 1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This tunneling technique is frequently used by IPv6 tunnel brokers like `Hurricane Electric`_.
+The encapsulation overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of 1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This tunneling technique is frequently used by IPv6 tunnel brokers like `Hurricane Electric`_. 
 
 An example:
 
@@ -75,6 +75,8 @@ An example:
   set interfaces tunnel tun0 remote-ip 192.0.2.20
   set interfaces tunnel tun0 address 2001:db8:bb::1/64
 
+A full example of a Tunnelbroker.net config can be found at :ref:`here <examples-tunnelbroker-ipv6>`.
+
 Generic Routing Encapsulation (GRE)
 -----------------------------------
 
@@ -191,4 +193,4 @@ Results in:
 .. _RFC2473: https://tools.ietf.org/html/rfc2473
 .. _`other proposals`: https://www.isc.org/downloads/aftr
 .. _RFC4213: https://tools.ietf.org/html/rfc4213
-.. _`Hurricane Electric`: https://tunnelbroker.net/
\ No newline at end of file
+.. _`Hurricane Electric`: https://tunnelbroker.net/
diff --git a/docs/routing/static.rst b/docs/routing/static.rst
index e1f96c31..4faa2451 100644
--- a/docs/routing/static.rst
+++ b/docs/routing/static.rst
@@ -13,11 +13,10 @@ not make use of DHCP or dynamic routing protocols:
   set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 distance '1'
 
 Another common use of static routes is to blackhole (drop) traffic. In the
-example below, RFC 1918 private IP networks are set as blackhole routes. This
-does not prevent networks within these segments from being used, since the
-most specific route is always used. It does, however, prevent traffic to
-unknown private networks from leaving the router. Commonly refereed to as
-leaking.
+example below, RFC1918_ networks are set as blackhole routes. 
+
+This prevents these networks leaking out public interfaces, but it does not prevent
+them from being used as the most specific route has the highest priority.
 
 .. code-block:: sh
 
@@ -27,3 +26,5 @@ leaking.
 
 .. note:: Routes with a distance of 255 are effectively disabled and not
    installed into the kernel.
+
+.. _RFC1918: https://tools.ietf.org/html/rfc1918