doc: clean up overview.rst, installation.rst

Just reading through the docs and fixing bugs as I go.

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

doc/user/installation.rst

@@ -5,27 +5,27 @@ Installation
 ************
 
 .. index:: How to install FRR
-
 .. index:: Installation
-
 .. index:: Installing FRR
-
 .. index:: Building the system
-
 .. index:: Making FRR
 
-There are three steps for installing the software: configuration,
+Several distributions provide packages for FRR. Check your distribution's
-compilation, and installation.
+respositories to find out if a suitable version is available.
 
-The easiest way to get FRR running is to issue the following
+If you wish to build FRR yourself, please see the `Building`_ appendix.
-commands:
+
+FRR depends on various libraries depending on your operationg system.
+
+After installing these dependencies, change to the frr source directory and issue the following commands:
 
 ::
 
-  % configure
+  % ./bootstrap.sh
+  % ./configure
   % make
   % make install
-  
+
 
 .. _Configure_the_Software:
 
@@ -133,9 +133,9 @@ customize the build to include or exclude specific features and dependencies.
   only tool and should not be used for normal operations
 
 You may specify any combination of the above options to the configure
-script.  By default, the executables are placed in :file:`/usr/local/sbin` 
+script.  By default, the executables are placed in :file:`/usr/local/sbin`
 and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/`
-installation prefix and other directories may be changed using the following 
+installation prefix and other directories may be changed using the following
 options to the configuration script.
 
 
@@ -154,7 +154,7 @@ options to the configuration script.
 ::
 
   % ./configure --disable-snmp
-  
+
 
 This command will configure zebra and the routing daemons.
 
@@ -180,7 +180,7 @@ options to control the behaviour of FRR daemons.
 
 *--enable-group=`group`*
   Switch real and effective group to `group` shortly after
-  startup. 
+  startup.
 
 *--enable-vty-group=`group`*
   Create Unix Vty sockets (for use with vtysh) with group owndership set to
@@ -233,7 +233,7 @@ recommendations do exist.
 
 
 *CONFIG_IP_MULTICAST*
-  IP: multicasting.  
+  IP: multicasting.
   This option should be specified when you use *ripd* (:ref:`RIP`) or
   *ospfd* (:ref:`OSPFv2`) because these protocols use multicast.
 
@@ -278,7 +278,7 @@ bug report :ref:`Bug_Reports`.
   % ./bootstrap.sh
   % ./configure <appropriate to your system>
   % make
-  
+
 
 @comment  node-name,  next,  previous,  up
 
@@ -298,7 +298,7 @@ prompt: *make install*.
   %
   % make install
   %
-  
+
 
 FRR daemons have their own terminal interface or VTY.  After
 installation, you have to setup each beast's port number to connect to
@@ -317,7 +317,7 @@ them.  Please add the following entries to :file:`/etc/services`.
   isisd         2608/tcp		  # ISISd vty
   nhrpd         2610/tcp		  # nhrpd vty
   pimd          2611/tcp		  # PIMd vty
-  
+
 
 If you use a FreeBSD newer than 2.2.8, the above entries are already
 added to :file:`/etc/services` so there is no need to add it. If you

doc/user/overview.rst

@@ -4,11 +4,9 @@
 Overview
 ********
 
-.. index:: Overview
+`FRR`_ is a routing software package that provides TCP/IP based
-
-`FRR <|PACKAGE_URL|>`_ is a routing software package that provides TCP/IP based
 routing services with routing protocols support such as RIPv1, RIPv2, RIPng,
-OSPFv2, OSPFv3, IS-IS, BGP-4, and BGP-4+ (:ref:`Supported_RFCs`). FRR also
+OSPFv2, OSPFv3, IS-IS, BGP-4, and BGP-4+ (:ref:`supported-rfcs`). FRR also
 supports special BGP Route Reflector and Route Server behavior.  In addition to
 traditional IPv4 routing protocols, FRR also supports IPv6 routing protocols.
 With SNMP daemon which supports SMUX and AgentX protocol, FRR provides routing
@@ -16,17 +14,17 @@ protocol MIBs (:ref:`SNMP_Support`).
 
 FRR uses an advanced software architecture to provide you with a high
 quality, multi server routing engine. FRR has an interactive user
-interface for each routing protocol and supports common client commands. 
+interface for each routing protocol and supports common client commands.
 Due to this design, you can add new protocol daemons to FRR easily.  You
 can use FRR library as your program's client user interface.
 
 FRR is distributed under the GNU General Public License.
 
+.. _About-FRR:
+
 About FRR
 =========
 
-.. index:: About FRR
-
 Today, TCP/IP networks are covering all of the world.  The Internet has
 been deployed in many countries, companies, and to the home.  When you
 connect to the Internet your packet will pass many routers which have TCP/IP
@@ -43,7 +41,7 @@ Adding to routing protocol support, FRR can setup interface's flags,
 interface's address, static routes and so on.  If you have a small network,
 or a stub network, or xDSL connection, configuring the FRR routing
 software is very easy.  The only thing you have to do is to set up the
-interfaces and put a few commands about static routes and/or default routes. 
+interfaces and put a few commands about static routes and/or default routes.
 If the network is rather large, or if the network structure changes
 frequently, you will want to take advantage of FRR's dynamic routing
 protocol support for protocols such as RIP, OSPF, IS-IS or BGP.
@@ -65,7 +63,6 @@ currently being prepared for merging.  Implementations of BFD and PIM-SSM
 The ultimate goal of the FRR project is making a productive, quality, free
 TCP/IP routing software package.
 
-@comment  node-name,  next,  previous,  up
 
 System Architecture
 ===================
@@ -86,7 +83,7 @@ The *ripd* daemon handles the RIP protocol, while
 *ospfd* is a daemon which supports OSPF version 2.
 *bgpd* supports the BGP-4 protocol.  For changing the kernel
 routing table and for redistribution of routes between different routing
-protocols, there is a kernel routing table manager *zebra* daemon. 
+protocols, there is a kernel routing table manager *zebra* daemon.
 It is easy to add a new routing protocol daemons to the entire routing
 system without affecting any other software.  You need to run only the
 protocol daemon associated with routing protocols in use.  Thus, user may
@@ -98,7 +95,6 @@ architecture creates new possibilities for the routing system.
 
 ::
 
-  @group
   +----+  +----+  +-----+  +-----+
   |bgpd|  |ripd|  |ospfd|  |zebra|
   +----+  +----+  +-----+  +-----+
@@ -110,8 +106,7 @@ architecture creates new possibilities for the routing system.
   +------------------------------+
 
       FRR System Architecture
-  @end group
+
-  
 
 Multi-process architecture brings extensibility, modularity and
 maintainability.  At the same time it also brings many configuration files
@@ -125,12 +120,11 @@ UNIX domain socket and then works as a proxy for user input.
 
 FRR was planned to use multi-threaded mechanism when it runs with a
 kernel that supports multi-threads.  But at the moment, the thread library
-which comes with @sc{gnu}/Linux or FreeBSD has some problems with running
+which comes with GNU/Linux or FreeBSD has some problems with running
-reliable services such as routing software, so we don't use threads at all. 
+reliable services such as routing software, so we don't use threads at all.
 Instead we use the *select(2)* system call for multiplexing the
 events.
 
-@comment  node-name,  next,  previous,  up
 
 Supported Platforms
 ===================
@@ -143,7 +137,7 @@ Supported Platforms
 
 .. index:: Operating systems that support FRR
 
-Currently FRR supports @sc{gnu}/Linux and BSD. Porting FRR
+Currently FRR supports GNU/Linux and BSD. Porting FRR
 to other platforms is not too difficult as platform dependent code should
 most be limited to the *zebra* daemon.  Protocol daemons are mostly
 platform independent. Please let us know when you find out FRR runs on a
@@ -153,213 +147,154 @@ The list of officially supported platforms are listed below. Note that
 FRR may run correctly on other platforms, and may run with partial
 functionality on further platforms.
 
-@sp 1
+- GNU/Linux
-
+- FreeBSD
-* 
+- NetBSD
-  @sc{gnu}/Linux
+- OpenBSD
-* 
-  FreeBSD
-* 
-  NetBSD
-* 
-  OpenBSD
 
 Versions of these platforms that are older than around 2 years from the point
-of their original release (in case of @sc{gnu}/Linux, this is since the kernel's
+of their original release (in case of GNU/Linux, this is since the kernel's
-release on kernel.org) may need some work.  Similarly, the following platforms
+release on https://kernel.org/) may need some work.  Similarly, the following platforms
 may work with some effort:
 
-@sp 1
+- Solaris
-
+- MacOS
-* 
-  Solaris
-* 
-  Mac OSX
 
 Also note that, in particular regarding proprietary platforms, compiler
 and C library choice will affect FRR.  Only recent versions of the
 following C compilers are well-tested:
 
-@sp 1
+- GNU's GCC
+- LLVM's clang
+- Intel's ICC
 
-* 
-  @sc{gnu}'s GCC
-* 
-  LLVM's clang
-* 
-  Intel's ICC
 
-@comment  node-name,  next,  previous,  up
+.. _supported-rfcs:
 
 Supported RFCs
 ==============
 
-Below is the list of currently supported RFC's.
+FRR implements the following RFCs:
 
+- :rfc:`1058`
+  :t:`Routing Information Protocol. C.L. Hedrick. Jun-01-1988.`
+- :rfc:`2082`
+  :t:`RIP-2 MD5 Authentication. F. Baker, R. Atkinson. January 1997.`
+- :rfc:`2453`
+  :t:`RIP Version 2. G. Malkin. November 1998.`
+- :rfc:`2080`
+  :t:`RIPng for IPv6. G. Malkin, R. Minnear. January 1997.`
+- :rfc:`2328`
+  :t:`OSPF Version 2. J. Moy. April 1998.`
+- :rfc:`2370`
+  :t:`The OSPF Opaque LSA Option R. Coltun. July 1998.`
+- :rfc:`3101`
+  :t:`The OSPF Not-So-Stubby Area (NSSA) Option P. Murphy. January 2003.`
+- :rfc:`2740`
+  :t:`OSPF for IPv6. R. Coltun, D. Ferguson, J. Moy. December 1999.`
+- :rfc:`1771`
+  :t:`A Border Gateway Protocol 4 (BGP-4). Y. Rekhter & T. Li. March 1995.`
+- :rfc:`1965`
+  :t:`Autonomous System Confederations for BGP. P. Traina. June 1996.`
+- :rfc:`1997`
+  :t:`BGP Communities Attribute. R. Chandra, P. Traina & T. Li. August 1996.`
+- :rfc:`2545`
+  :t:`Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing. P.
+  Marques, F. Dupont. March 1999.`
+- :rfc:`2796`
+  :t:`BGP Route Reflection An alternative to full mesh IBGP. T. Bates & R.
+  Chandrasekeran. June 1996.`
+- :rfc:`2858`
+  :t:`Multiprotocol Extensions for BGP-4. T. Bates, Y. Rekhter, R. Chandra, D.
+  Katz. June 2000.`
+- :rfc:`2842`
+  :t:`Capabilities Advertisement with BGP-4. R. Chandra, J. Scudder. May 2000.`
+- :rfc:`3137`
+  :t:`OSPF Stub Router Advertisement, A. Retana, L. Nguyen, R. White, A. Zinin,
+  D. McPherson. June 2001`
 
+**When SNMP support is enabled, the following RFCs are also supported:**
 
-*@asis{RFC1058}*
+- :rfc:`1227`
-  @cite{Routing Information Protocol. C.L. Hedrick. Jun-01-1988.}
+  :t:`SNMP MUX protocol and MIB. M.T. Rose. May-01-1991.`
-
+- :rfc:`1657`
-
+  :t:`Definitions of Managed Objects for the Fourth Version of the Border
-*@asis{RF2082}*
+  Gateway Protocol (BGP-4) using SMIv2. S. Willis, J. Burruss, J. Chu, Editor.
-  @cite{RIP-2 MD5 Authentication. F. Baker, R. Atkinson. January 1997.}
+  July 1994.`
-
+- :rfc:`1724`
-
+  :t:`RIP Version 2 MIB Extension. G. Malkin & F. Baker. November 1994.`
-*@asis{RFC2453}*
+- :rfc:`1850`
-  @cite{RIP Version 2. G. Malkin. November 1998.}
+  :t:`OSPF Version 2 Management Information Base. F. Baker, R. Coltun.
-
+  November 1995.`
-
+- :rfc:`2741`
-*@asis{RFC2080}*
+  :t:`Agent Extensibility (AgentX) Protocol. M. Daniele, B. Wijnen. January 2000.`
-  @cite{RIPng for IPv6. G. Malkin, R. Minnear. January 1997.}
-
-
-*@asis{RFC2328}*
-  @cite{OSPF Version 2. J. Moy. April 1998.}
-
-
-*@asis{RFC2370}*
-  @cite{The OSPF Opaque LSA Option R. Coltun. July 1998.}
-
-
-*@asis{RFC3101}*
-  @cite{The OSPF Not-So-Stubby Area (NSSA) Option P. Murphy. January 2003.}
-
-
-*@asis{RFC2740}*
-  @cite{OSPF for IPv6. R. Coltun, D. Ferguson, J. Moy. December 1999.}
-
-
-*@asis{RFC1771}*
-  @cite{A Border Gateway Protocol 4 (BGP-4). Y. Rekhter & T. Li. March 1995.}
-
-
-*@asis{RFC1965}*
-  @cite{Autonomous System Confederations for BGP. P. Traina. June 1996.}
-
-
-*@asis{RFC1997}*
-  @cite{BGP Communities Attribute. R. Chandra, P. Traina & T. Li. August 1996.}
-
-
-*@asis{RFC2545}*
-  @cite{Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing. P. Marques, F. Dupont. March 1999.}
-
-
-*@asis{RFC2796}*
-  @cite{BGP Route Reflection An alternative to full mesh IBGP. T. Bates & R. Chandrasekeran. June 1996.}
-
-
-*@asis{RFC2858}*
-  @cite{Multiprotocol Extensions for BGP-4. T. Bates, Y. Rekhter, R. Chandra, D. Katz. June 2000.}
-
-
-*@asis{RFC2842}*
-  @cite{Capabilities Advertisement with BGP-4. R. Chandra, J. Scudder. May 2000.}
-
-
-*@asis{RFC3137}*
-  @cite{OSPF Stub Router Advertisement, A. Retana, L. Nguyen, R. White, A. Zinin, D. McPherson. June 2001}
-
-When SNMP support is enabled, below RFC is also supported.
-
-
-
-*@asis{RFC1227}*
-  @cite{SNMP MUX protocol and MIB. M.T. Rose. May-01-1991.}
-
-
-*@asis{RFC1657}*
-  @cite{Definitions of Managed Objects for the Fourth Version of the
-  Border Gateway Protocol (BGP-4) using SMIv2. S. Willis, J. Burruss,
-  J. Chu, Editor. July 1994.}
-
-
-*@asis{RFC1724}*
-  @cite{RIP Version 2 MIB Extension. G. Malkin & F. Baker. November 1994.}
-
-
-*@asis{RFC1850}*
-  @cite{OSPF Version 2 Management Information Base. F. Baker, R. Coltun.
-  November 1995.}
-
-
-*@asis{RFC2741}*
-  @cite{Agent Extensibility (AgentX) Protocol. M. Daniele, B. Wijnen. January 2000.}
-
-
-@comment  node-name,  next,  previous,  up
 
 How to get FRR
 ==============
 
-The official FRR web-site is located at:
+The official FRR website is located at |PACKAGE_URL| and contains further
+information, as well as links to additional resources.
 
-`|PACKAGE_URL| <|PACKAGE_URL|>`_
+FRR is a fork of `Quagga <http://www.quagga.net/>`_.
 
-and contains further information, as well as links to additional
+Mailing Lists
-resources. 
+=============
-
-FRR is a fork of Quagga, whose website is located at:
-
-`http://www.quagga.net/ <http://www.quagga.net/>`_.
-
-@comment  node-name,  next,  previous,  up
-
-Mailing List
-============
 
 .. index:: How to get in touch with FRR
-
-.. index:: Mailing FRR
-
 .. index:: Contact information
-
 .. index:: Mailing lists
 
-There is a mailing list for discussions about FRR.  If you have any
-comments or suggestions to FRR, please subscribe to:
 
-`https://lists.frrouting.org/listinfo/frog <https://lists.frrouting.org/listinfo/frog>`_.
+Italicized lists are private.
 
-The `FRR <|PACKAGE_URL|>`_ site has further information on
++--------------------------------+------------------------------+
-the available mailing lists, see:
+| Topic                          | List                         |
++================================+==============================+
+| Development                    | dev@lists.frrouting.org      |
++--------------------------------+------------------------------+
+| Users & Operators              | frog@lists.frrouting.org     |
++--------------------------------+------------------------------+
+| Announcements                  | announce@lists.frrouting.org |
++--------------------------------+------------------------------+
+| *Security*                     | security@lists.frrouting.org |
++--------------------------------+------------------------------+
+| *Technical Steering Committee* | tsc@lists.frrouting.org      |
++--------------------------------+------------------------------+
 
-`https://lists.frrouting.org/ <https://lists.frrouting.org/>`_
+The Development list is used to discuss and document general issues related to
+project development and governance. The public `Slack instance
+<https://frrouting.slack.com>`_, and weekly technical meetings provide a higher
+bandwidth channel for discussions. The results of such discussions are
+reflected in updates, as appropriate, to code (i.e., merges), `GitHub
+<https://github.com/FRRouting/frr/issues>`_ tracked issues, and for governance
+or process changes, updates to the Development list and either this file or
+information posted at https://frrouting.org/.
 
 Bug Reports
 ===========
 
 .. index:: Bug Reports
-
 .. index:: Bug hunting
-
 .. index:: Found a bug?
-
 .. index:: Reporting bugs
-
 .. index:: Reporting software errors
-
 .. index:: Errors in the software
 
-If you think you have found a bug, please send a bug report to:
+If you think you have found a bug, please file a bug report on our
-
+`GitHub issues`_ page.
-`http://github.com/frrouting/frr/issues <http://github.com/frrouting/frr/issues>`_
 
 When you send a bug report, please be careful about the points below.
 
-* 
+- Please note what kind of OS you are using.  If you use the IPv6 stack
-  Please note what kind of OS you are using.  If you use the IPv6 stack
   please note that as well.
-* 
+- Please show us the results of `netstat -rn` and `ifconfig -a`.
-  Please show us the results of `netstat -rn` and `ifconfig -a`.
   Information from zebra's VTY command `show ip route` will also be
   helpful.
-* 
+- Please send your configuration file with the report.  If you specify
-  Please send your configuration file with the report.  If you specify
   arguments to the configure script please note that too.
 
-Bug reports are very important for us to improve the quality of FRR.
+Bug reports help us improve FRR and are very much appreciated.
-FRR is still in the development stage, but please don't hesitate to
-send a bug report to `http://github.com/frrouting/frr/issues <http://github.com/frrouting/frr/issues>`_.
 
+.. _FRR: |PACKAGE_URL|
+.. _GitHub: http://github.com/frrouting/frr/
+.. _GitHub issues: http://github.com/frrouting/frr/