doc: cleanup installation instructions

Use program and option directives for CLI options

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

diff --git a/doc/user/basic.rst b/doc/user/basic.rst
index 933d49b01a5c20de4035550d7c03db3d6cf72110..58c8caa4e3160dbf7b0ecd9165b90d21d591a71a 100644 (file)
--- a/doc/user/basic.rst
+++ b/doc/user/basic.rst
@@ -37,16 +37,12 @@ routing daemon configurations, a log file name, and so forth. This
 information forms the initial command set for a routing beast as it is
 starting.
 
-Config files are generally found in:
-
-* :file:`|INSTALL_PREFIX_ETC|`/\*.conf
+Config files are generally found in |INSTALL_PREFIX_ETC|.
 
 Each of the daemons has its own
-config file. For example, zebra's default config file name is:
-
-* :file:`INSTALL_PREFIX_ETC`/zebra.conf
+config file. For example, zebra's default config file name is *zebra.conf*.
 
-The daemon name plus :file:`.conf` is the default config file name. You
+The daemon name plus `.conf` is the default config file name. You
 can specify a config file using the :kbd:`-f` or :kbd:`--config-file`
 options when starting the daemon.
 

diff --git a/doc/user/installation.rst b/doc/user/installation.rst
index a60d09dd4380d61bec9667f93f2eb9686bf9f8d3..70d1a7c5b10989108ee59b6cbd00775b5a3db7c2 100644 (file)
--- a/doc/user/installation.rst
+++ b/doc/user/installation.rst
@@ -33,10 +33,10 @@ Configure the Software
 ======================
 
 
-.. _The_Configure_script_and_its_options:
+.. _The_Configure_Script:
 
-The Configure script and its options
-------------------------------------
+The Configure Script
+--------------------
 
 .. index:: Configuration options
 
@@ -52,111 +52,132 @@ FRR has an excellent configure script which automatically detects most
 host configurations.  There are several additional configure options to
 customize the build to include or exclude specific features and dependencies.
 
+.. program:: configure
 
+.. option:: --disable-zebra
 
-*--disable-zebra*
-  Do not build zebra daemon.
 
-*--disable-ripd*
-  Do not build ripd.
+   Do not build zebra daemon.
 
-*--disable-ripngd*
-  Do not build ripngd.
+.. option:: --disable-ripd
 
-*--disable-ospfd*
-  Do not build ospfd.
+   Do not build ripd.
 
-*--disable-ospf6d*
-  Do not build ospf6d.
+.. option:: --disable-ripngd
 
-*--disable-bgpd*
-  Do not build bgpd.
+   Do not build ripngd.
 
-*--disable-bgp-announce*
-  Make *bgpd* which does not make bgp announcements at all.  This
-  feature is good for using *bgpd* as a BGP announcement listener.
+.. option:: --disable-ospfd
 
-*--enable-datacenter*
-  Enable system defaults to work as if in a Data Center. See defaults.h
-  for what is changed by this configure option.
+   Do not build ospfd.
 
-*--enable-snmp*
-  Enable SNMP support.  By default, SNMP support is disabled.
+.. option:: --disable-ospf6d
 
-*--disable-ospfapi*
-  Disable support for OSPF-API, an API to interface directly with ospfd.
-  OSPF-API is enabled if --enable-opaque-lsa is set.
+   Do not build ospf6d.
 
-*--disable-ospfclient*
-  Disable building of the example OSPF-API client.
+.. option:: --disable-bgpd
 
-*--disable-ospf-ri*
-  Disable support for OSPF Router Information (RFC4970 & RFC5088) this
-  requires support for Opaque LSAs and Traffic Engineering.
+   Do not build bgpd.
 
-*--disable-isisd*
-  Do not build isisd.
+.. option:: --disable-bgp-announce
 
-*--enable-isis-topology*
-  Enable IS-IS topology generator.
+   Make *bgpd* which does not make bgp announcements at all.  This
+   feature is good for using *bgpd* as a BGP announcement listener.
 
-*--enable-isis-te*
-  Enable Traffic Engineering Extension for ISIS (RFC5305)
+.. option:: --enable-datacenter
 
-*--enable-multipath=`ARG`*
-  Enable support for Equal Cost Multipath. `ARG` is the maximum number
-  of ECMP paths to allow, set to 0 to allow unlimited number of paths.
+   Enable system defaults to work as if in a Data Center. See defaults.h
+   for what is changed by this configure option.
 
-*--disable-rtadv*
-  Disable support IPV6 router advertisement in zebra.
+.. option:: --enable-snmp
 
-*--enable-gcc-rdynamic*
-  Pass the *-rdynamic* option to the linker driver.  This is in most
-  cases neccessary for getting usable backtraces.  This option defaults to on
-  if the compiler is detected as gcc, but giving an explicit enable/disable is
-  suggested.
+   Enable SNMP support.  By default, SNMP support is disabled.
 
-*--disable-backtrace*
-  Controls backtrace support for the crash handlers. This is autodetected by
-  default. Using the switch will enforce the requested behaviour, failing with
-  an error if support is requested but not available.  On BSD systems, this
-  needs libexecinfo, while on glibc support for this is part of libc itself.
+.. option:: --disable-ospfapi
 
-*--enable-dev-build*
-  Turn on some options for compiling FRR within a development environment in
-  mind.  Specifically turn on -g3 -O0 for compiling options and add inclusion
-  of grammar sandbox.
+   Disable support for OSPF-API, an API to interface directly with ospfd.
+   OSPF-API is enabled if --enable-opaque-lsa is set.
+
+.. option:: --disable-ospfclient
+
+   Disable building of the example OSPF-API client.
+
+.. option:: --disable-ospf-ri
+
+   Disable support for OSPF Router Information (RFC4970 & RFC5088) this
+   requires support for Opaque LSAs and Traffic Engineering.
+
+.. option:: --disable-isisd
+
+   Do not build isisd.
+
+.. option:: --enable-isis-topology
+
+   Enable IS-IS topology generator.
+
+.. option:: --enable-isis-te
+
+   Enable Traffic Engineering Extension for ISIS (RFC5305)
+
+.. option:: --enable-multipath=`ARG`
+
+   Enable support for Equal Cost Multipath. `ARG` is the maximum number
+   of ECMP paths to allow, set to 0 to allow unlimited number of paths.
+
+.. option:: --disable-rtadv
+
+   Disable support IPV6 router advertisement in zebra.
+
+.. option:: --enable-gcc-rdynamic
+
+   Pass the *-rdynamic* option to the linker driver.  This is in most
+   cases neccessary for getting usable backtraces.  This option defaults to on
+   if the compiler is detected as gcc, but giving an explicit enable/disable is
+   suggested.
+
+.. option:: --disable-backtrace
+
+   Controls backtrace support for the crash handlers. This is autodetected by
+   default. Using the switch will enforce the requested behaviour, failing with
+   an error if support is requested but not available.  On BSD systems, this
+   needs libexecinfo, while on glibc support for this is part of libc itself.
+
+.. option:: --enable-dev-build
+
+   Turn on some options for compiling FRR within a development environment in
+   mind.  Specifically turn on -g3 -O0 for compiling options and add inclusion
+   of grammar sandbox.
+
+.. option:: --enable-fuzzing
+
+   Turn on some compile options to allow you to run fuzzing tools against the
+   system. This flag is intended as a developer only tool and should not be
+   used for normal operations.
+
+.. option:: --disable-snmp
+
+   Build without SNMP support.
 
-*--enable-fuzzing*
-  Turn on some compile options to allow you to run fuzzing tools
-  against the system.  This tools is intended as a developer
-  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
 options to the configuration script.
 
+.. option:: --prefix=`prefix`
 
+   Install architecture-independent files in `prefix` [/usr/local].
 
-*--prefix=`prefix`*
-  Install architecture-independent files in `prefix` [/usr/local].
-
-*--sysconfdir=`dir`*
-  Look for configuration files in `dir` [`prefix`/etc]. Note
-  that sample configuration files will be installed here.
-
-*--localstatedir=`dir`*
-  Configure zebra to use `dir` for local state files, such
-  as pid files and unix sockets.
-
-::
+.. option:: --sysconfdir=`dir`
 
-  % ./configure --disable-snmp
+   Look for configuration files in `dir` [`prefix`/etc]. Note that sample
+   configuration files will be installed here.
 
+.. option:: --localstatedir=`dir`
 
-This command will configure zebra and the routing daemons.
+   Configure zebra to use `dir` for local state files, such
+   as pid files and unix sockets.
 
 .. _Least-Privilege_support:
 
@@ -172,34 +193,34 @@ shortly after startup and switch to another user. The configure script will
 automatically try to configure this support. There are three configure
 options to control the behaviour of FRR daemons.
 
+.. option:: --enable-user=`user`
 
+   Switch to user `ARG` shortly after startup, and run as user `ARG`
+   in normal operation.
 
-*--enable-user=`user`*
-  Switch to user `ARG` shortly after startup, and run as user `ARG`
-  in normal operation.
+.. option:: --enable-group=`group`
 
-*--enable-group=`group`*
-  Switch real and effective group to `group` shortly after
-  startup.
+   Switch real and effective group to `group` shortly after
+   startup.
 
-*--enable-vty-group=`group`*
-  Create Unix Vty sockets (for use with vtysh) with group owndership set to
-  `group`. This allows one to create a seperate group which is
-  restricted to accessing only the Vty sockets, hence allowing one to
-  delegate this group to individual users, or to run vtysh setgid to
-  this group.
+.. option:: --enable-vty-group=`group`
+
+   Create Unix Vty sockets (for use with vtysh) with group owndership set to
+   `group`. This allows one to create a seperate group which is
+   restricted to accessing only the Vty sockets, hence allowing one to
+   delegate this group to individual users, or to run vtysh setgid to
+   this group.
 
 The default user and group which will be configured is 'frr' if no user
 or group is specified. Note that this user or group requires write access to
-the local state directory (see --localstatedir) and requires at least read
+the local state directory (see `--localstatedir`) and requires at least read
 access, and write access if you wish to allow daemons to write out their
-configuration, to the configuration directory (see --sysconfdir).
+configuration, to the configuration directory (see `--sysconfdir`).
 
-On systems which have the 'libcap' capabilities manipulation library
-(currently only linux), the frr system will retain only minimal
-capabilities required, further it will only raise these capabilities for
-brief periods. On systems without libcap, frr will run as the user
-specified and only raise its uid back to uid 0 for brief periods.
+On systems which have the 'libcap' capabilities manipulation library (currently
+only Linux), FRR will retain only minimal capabilities required and will only
+raise these capabilities for brief periods. On systems without libcap, FRR will
+run as the user specified and only raise its UID to 0 for brief periods.
 
 .. _Linux_Notes:
 
@@ -219,33 +240,25 @@ what you want.  FRR will run with any kernel configuration but some
 recommendations do exist.
 
 
-
-*CONFIG_NETLINK*
+- CONFIG_NETLINK
   Kernel/User netlink socket. This is a brand new feature which enables an
   advanced interface between the Linux kernel and zebra (:ref:`Kernel_Interface`).
-
-
-*CONFIG_RTNETLINK*
+- CONFIG_RTNETLINK
   Routing messages.
   This makes it possible to receive netlink routing messages.  If you
   specify this option, *zebra* can detect routing information
   updates directly from the kernel (:ref:`Kernel_Interface`).
-
-
-*CONFIG_IP_MULTICAST*
+- CONFIG_IP_MULTICAST
   IP: multicasting.
   This option should be specified when you use *ripd* (:ref:`RIP`) or
   *ospfd* (:ref:`OSPFv2`) because these protocols use multicast.
 
-
 IPv6 support has been added in GNU/Linux kernel version 2.2.  If you
 try to use the FRR IPv6 feature on a GNU/Linux kernel, please
 make sure the following libraries have been installed.  Please note that
 these libraries will not be needed when you uses GNU C library 2.1
 or upper.
 
-
-
 *inet6-apps*
   The `inet6-apps` package includes basic IPv6 related libraries such
   as `inet_ntop` and `inet_pton`.  Some basic IPv6 programs such
@@ -266,22 +279,19 @@ or upper.
 Build the Software
 ==================
 
-After configuring the software, you will need to compile it for your
-system. Simply issue the command *make* in the root of the source
-directory and the software will be compiled. Cliff Note versions of
-different compilation examples can be found in the doc/Building_FRR_on_XXX.md
-files.  If you have *any* problems at this stage, be certain to send a
-bug report :ref:`Bug_Reports`.
+After configuring the software, you will need to compile it for your system.
+Simply issue the command *make* in the root of the source directory and the
+software will be compiled. Cliff Notes versions of different compilation
+examples can be found in the Developer's Manual Appendix.  If you have *any*
+problems at this stage, please send a bug report :ref:`Bug_Reports`.
 
 ::
 
-  % ./bootstrap.sh
-  % ./configure <appropriate to your system>
-  % make
+  $ ./bootstrap.sh
+  $ ./configure <appropriate to your system>
+  $ make
 
 
-@comment  node-name,  next,  previous,  up
-
 Install the Software
 ====================
 
@@ -291,18 +301,13 @@ installation process has completed, these files have been copied
 from your work directory to :file:`/usr/local/bin`, and :file:`/usr/local/etc`.
 
 To install the FRR suite, issue the following command at your shell
-prompt: *make install*.
-
-::
-
-  %
-  % make install
-  %
+prompt:::
 
+  $ 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
-them.  Please add the following entries to :file:`/etc/services`.
+them. Please add the following entries to :file:`/etc/services`.
 
 ::
 
@@ -325,5 +330,5 @@ specify a port number when starting the daemon, these entries may not be
 needed.
 
 You may need to make changes to the config files in
-:file:`|INSTALL_PREFIX_ETC`/\*.conf|. :ref:`Config_Commands`.
+|INSTALL_PREFIX_ETC|. :ref:`Config_Commands`.