docs: reformat man pages to improve consistency and readability
Change-Id: I4f9afbc73c365dfa31eb6cd1e4a48368b6a9064f
diff --git a/docs/manpages/nfdc-route.rst b/docs/manpages/nfdc-route.rst
index 8c7cffa..5a4982d 100644
--- a/docs/manpages/nfdc-route.rst
+++ b/docs/manpages/nfdc-route.rst
@@ -1,20 +1,22 @@
nfdc-route
==========
-SYNOPSIS
+Synopsis
--------
-| nfdc route [list [[nexthop] <FACEID|FACEURI>] [origin <ORIGIN>]]
-| nfdc route show [prefix] <PREFIX>
-| nfdc route add [prefix] <PREFIX> [nexthop] <FACEID|FACEURI> [origin <ORIGIN>]
-| [cost <COST>] [no-inherit] [capture] [expires <EXPIRATION-MILLIS>]
-| nfdc route remove [prefix] <PREFIX> [nexthop] <FACEID|FACEURI> [origin <ORIGIN>]
-| nfdc fib [list]
-DESCRIPTION
+| **nfdc route** [**list** [[**nexthop**] *FACEID*\|\ *FACEURI*] [**origin** *ORIGIN*]]
+| **nfdc route** **show** [**prefix**] *PREFIX*
+| **nfdc route** **add** [**prefix**] *PREFIX* [**nexthop**] *FACEID*\|\ *FACEURI* [**origin** *ORIGIN*] \
+ [**cost** *COST*] [**no-inherit**] [**capture**] [**expires** *EXPIRATION*]
+| **nfdc route** **remove** [**prefix**] *PREFIX* [**nexthop**] *FACEID*\|\ *FACEURI* [**origin** *ORIGIN*]
+| **nfdc fib** [**list**]
+
+Description
-----------
+
In NFD, the routing information base (RIB) stores static or dynamic routing information
registered by applications, operators, and NFD itself.
-Each *route* in the RIB indicates that contents under a name prefix may be available via a nexthop.
+Each route in the RIB indicates that contents under a name prefix may be available via a nexthop.
A route contains a name prefix, a nexthop face, the origin, a cost, and a set of route inheritance flags;
refer to NFD Management protocol for more information.
@@ -26,86 +28,108 @@
If a route with the same prefix, nexthop, and origin already exists,
it is updated with the specified cost, route inheritance flags, and expiration period.
This command returns when the request has been accepted, but does not wait for RIB update completion.
-If no face matching the specified URI is found, nfdc will attempt to implicitly create a face with
-this URI before adding the route.
+If no face matching the specified URI is found, :program:`nfdc` will attempt to implicitly create a face
+with this URI before adding the route.
The **nfdc route remove** command removes a route with matching prefix, nexthop, and origin.
The **nfdc fib list** command shows the forwarding information base (FIB),
which is calculated from RIB routes and used directly by NFD forwarding.
-OPTIONS
+Options
-------
-<PREFIX>
+
+.. option:: <PREFIX>
+
Name prefix of the route.
-<FACEID>
+.. option:: <FACEID>
+
Numerical identifier of the face.
It is displayed in the output of **nfdc face list** and **nfdc face create** commands.
-<FACEURI>
+.. option:: <FACEURI>
+
An URI representing the remote endpoint of a face.
In **nfdc route add** command, it must uniquely match an existing face.
In **nfdc route remove** command, it must match one or more existing faces.
-<ORIGIN>
- Origin of the route, i.e. who is announcing the route.
+ See the `FaceUri section <https://redmine.named-data.net/projects/nfd/wiki/FaceMgmt#FaceUri>`__
+ of the NFD Face Management protocol for more details on the syntax.
+
+.. option:: <ORIGIN>
+
+ Origin of the route, i.e., who is announcing the route.
The default is 255, indicating a static route.
-<COST>
+.. option:: <COST>
+
The administrative cost of the route.
The default is 0.
-no-inherit
- Unset CHILD_INHERIT flag in the route.
+.. option:: no-inherit
-capture
- Set CAPTURE flag in the route.
+ Unset ``CHILD_INHERIT`` flag in the route.
-<EXPIRATION-MILLIS>
+.. option:: capture
+
+ Set ``CAPTURE`` flag in the route.
+
+.. option:: <EXPIRATION>
+
Expiration time of the route, in milliseconds.
When the route expires, NFD removes it from the RIB.
The default is infinite, which keeps the route active until the nexthop face is destroyed.
-EXIT CODES
-----------
-0: Success
+Exit Status
+-----------
-1: An unspecified error occurred
+0
+ Success.
-2: Malformed command line
+1
+ An unspecified error occurred.
-3: Face not found
+2
+ Malformed command line.
-4: FaceUri canonization failed
+3
+ Face not found.
-5: Ambiguous: multiple matching faces are found (**nfdc route add** only)
+4
+ FaceUri canonization failed.
-6: Route not found (**nfdc route list** and **nfdc route show** only)
+5
+ Ambiguous: multiple matching faces are found (**nfdc route add** only).
-EXAMPLES
+6
+ Route not found (**nfdc route list** and **nfdc route show** only).
+
+Examples
--------
-nfdc route list
+
+``nfdc route list``
List all routes.
-nfdc route list nexthop 300
+``nfdc route list nexthop 300``
List routes whose nexthop is face 300.
-nfdc route list origin static
+``nfdc route list origin static``
List static routes.
-nfdc route show prefix /localhost/nfd
+``nfdc route show prefix /localhost/nfd``
List routes with name prefix "/localhost/nfd".
-nfdc route add prefix /ndn nexthop 300 cost 100
+``nfdc route add prefix /ndn nexthop 300 cost 100``
Add a route with prefix "/ndn" toward face 300, with administrative cost 100.
-nfdc route add prefix / nexthop udp://router.example.net
+``nfdc route add prefix / nexthop udp://router.example.net``
Add a route with prefix "/" toward a face with the specified remote FaceUri.
-nfdc route remove prefix /ndn nexthop 300 origin static
+``nfdc route remove prefix /ndn nexthop 300 origin static``
Remove the route whose prefix is "/ndn", nexthop is face 300, and origin is "static".
-SEE ALSO
+See Also
--------
-nfd(1), nfdc(1)
+
+:manpage:`nfdc(1)`