docs: reformat man pages to improve consistency and readability
Change-Id: I4f9afbc73c365dfa31eb6cd1e4a48368b6a9064f
diff --git a/docs/manpages/ndn-autoconfig-server.rst b/docs/manpages/ndn-autoconfig-server.rst
index 369252e..a5b6bff 100644
--- a/docs/manpages/ndn-autoconfig-server.rst
+++ b/docs/manpages/ndn-autoconfig-server.rst
@@ -34,16 +34,20 @@
``-V``
Print version number and exit.
-Exit status
+Exit Status
-----------
-0: No error.
+0
+ No error.
-1: An unspecified error occurred.
+1
+ An unspecified error occurred.
-2: Malformed command line, e.g., invalid, missing, or unknown argument.
+2
+ Malformed command line, e.g., invalid, missing, or unknown argument.
-4: Insufficient privileges.
+4
+ Insufficient privileges.
Examples
--------
@@ -54,7 +58,7 @@
ndn-autoconfig-server -p /ndn/edu/ucla tcp://spurs.cs.ucla.edu
-See also
+See Also
--------
-:ref:`ndn-autoconfig`
+:manpage:`ndn-autoconfig(1)`
diff --git a/docs/manpages/ndn-autoconfig.rst b/docs/manpages/ndn-autoconfig.rst
index c455bb9..c1294b6 100644
--- a/docs/manpages/ndn-autoconfig.rst
+++ b/docs/manpages/ndn-autoconfig.rst
@@ -172,18 +172,23 @@
If this query is answered, connect to the home hub and terminate auto-discovery.
Otherwise, the auto-discovery fails.
-Exit status
+Exit Status
-----------
-0: No error.
+0
+ No error.
-1: An unspecified error occurred.
+1
+ An unspecified error occurred.
-2: Malformed command line, e.g., invalid, missing, or unknown argument.
+2
+ Malformed command line, e.g., invalid, missing, or unknown argument.
-4: Insufficient privileges.
+4
+ Insufficient privileges.
-See also
+See Also
--------
-:ref:`ndn-autoconfig-server`, :doc:`ndn-autoconfig.conf`
+:manpage:`ndn-autoconfig-server(1)`,
+:doc:`ndn-autoconfig.conf`
diff --git a/docs/manpages/nfd-asf-strategy.rst b/docs/manpages/nfd-asf-strategy.rst
index 0847144..45339b8 100644
--- a/docs/manpages/nfd-asf-strategy.rst
+++ b/docs/manpages/nfd-asf-strategy.rst
@@ -5,7 +5,7 @@
--------
**nfdc strategy set** **prefix** *NAME* **strategy**
-/localhost/nfd/strategy/asf[/v=4][/**probing-interval**\ ~\ *INTERVAL*][/**max-timeouts**\ ~\ *TIMEOUTS*]
+/localhost/nfd/strategy/asf[/v=5][/**probing-interval**\ ~\ *INTERVAL*][/**max-timeouts**\ ~\ *TIMEOUTS*]
Description
-----------
@@ -17,14 +17,14 @@
Options
-------
-.. option:: probing-interval
+.. option:: probing-interval <INTERVAL>
This optional parameter tells ASF how often to send a probe to determine
alternative paths. The value is specified in milliseconds (non-negative
integer). Smaller values will result in higher overhead but faster reaction.
The default value is 1 minute and the minimum value is 1 second.
-.. option:: max-timeouts
+.. option:: max-timeouts <TIMEOUTS>
This optional parameter makes ASF switch to another appropriate face (if available)
after it has encountered the specified number of timeouts. The value is a positive
@@ -36,24 +36,24 @@
Examples
--------
-nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf
+``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf``
Use the default values for all parameters.
-nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=4/probing-interval~30000
+``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=5/probing-interval~30000``
Set the probing interval to 30 seconds.
-nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=4/max-timeouts~5
+``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=5/max-timeouts~5``
Set the maximum number of timeouts to 5.
-nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=4/probing-interval~30000/max-timeouts~2
+``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=5/probing-interval~30000/max-timeouts~2``
Set the probing interval to 30 seconds and the maximum number of timeouts to 2.
-nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=4/retx-suppression-multiplier~2.5/probing-interval~45000
+``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/asf/v=5/retx-suppression-multiplier~2.5/probing-interval~45000``
Set the retransmission suppression multiplier to 2.5 and the probing interval
to 45 seconds. See :manpage:`nfdc-strategy(1)` for more information on the
retransmission suppression parameters.
-See also
+See Also
--------
-nfdc(1), nfdc-strategy(1)
+:manpage:`nfdc-strategy(1)`
diff --git a/docs/manpages/nfd-autoreg.rst b/docs/manpages/nfd-autoreg.rst
index 3ce898a..58390d6 100644
--- a/docs/manpages/nfd-autoreg.rst
+++ b/docs/manpages/nfd-autoreg.rst
@@ -4,12 +4,16 @@
Synopsis
--------
-**nfd-autoreg** --prefix=</autoreg/prefix> [--prefix=</another/prefix>]...
+| **nfd-autoreg** [**-i**\|\ **\--prefix** *prefix*]... [**-a**\|\ **\--all-faces-prefix** *prefix*]...
+| [**-b**\|\ **\--blacklist** *network*]... [**-w**\|\ **\--whitelist** *network*]... \
+ [**-c**\|\ **\--cost** *cost*]
+| **nfd-autoreg** **-h**\|\ **\--help**
+| **nfd-autoreg** **-V**\|\ **\--version**
Description
-----------
-``nfd-autoreg`` is a daemon application that automatically registers the specified
+:program:`nfd-autoreg` is a daemon application that automatically registers the specified
prefix(es) when new on-demand faces are created (i.e., when a new UDP face is created as
the result of an incoming packet or when a new TCP face is created as the result of an
incoming connection).
@@ -17,53 +21,61 @@
Options
-------
-``-i`` or ``--prefix``
- Prefix that should be automatically registered when a new remote face is created.
- Can be repeated multiple times to specify additional prefixes.
+.. option:: -i <prefix>, --prefix <prefix>
-``-c`` or ``--cost``
- RIB cost to be assigned to auto-registered prefixes. If not specified, default cost
- is set to 255.
+ Prefix that should be automatically registered when a new remote face is created.
+ Can be repeated multiple times to specify additional prefixes.
-``-w`` or ``--whitelist``
- Whitelisted network, e.g., 192.168.2.0/24 or ::1/128. Can be repeated multiple times
- to specify multiple whitelisted networks.
+.. option:: -b <network>, --blacklist <network>
- Prefix(es) will be auto-registered only when remote IP address is within the specified
- range(s), except blacklist ranges.
+ Blacklisted network, e.g., 192.168.2.32/30 or ::1/128. Can be repeated multiple times
+ to specify multiple blacklisted networks.
- Default: 0.0.0.0/0 and ::/0
+ The prefixes will be auto-registered only when the remote IP address is NOT inside the
+ specified range(s), but is inside the range defined by the whitelist(s), if any.
-``-b`` or ``--blacklist``
- Blacklisted network, e.g., 192.168.2.32/30 or ::1/128. Can be repeated multiple times
- to specify multiple blacklisted networks.
+ Default: none.
- Prefix(es) will be auto-registered only when remote IP address in **NOT** within the
- specified range(s), but is within the range define by the whitelist(s).
+.. option:: -w <network>, --whitelist <network>
- Default: none
+ Whitelisted network, e.g., 192.168.2.0/24 or ::1/128. Can be repeated multiple times
+ to specify multiple whitelisted networks.
-``-h`` or ``--help``
- Print help message and exit.
+ The prefixes will be auto-registered only when the remote IP address is inside the
+ specified range(s), excluding any blacklisted range(s).
-``-V`` or ``--version``
- Show version information and exit.
+ Default: 0.0.0.0/0 and ::/0.
-Exit status
+.. option:: -c <cost>, --cost <cost>
+
+ RIB cost to assign to auto-registered prefixes. If not specified, the cost is set to 255.
+
+.. option:: -h, --help
+
+ Print help message and exit.
+
+.. option:: -V, --version
+
+ Show version information and exit.
+
+Exit Status
-----------
-0: No error.
+0
+ No error.
-1: An unspecified error occurred.
+1
+ An unspecified error occurred.
-2: Malformed command line, e.g., invalid, missing, or unknown argument.
+2
+ Malformed command line, e.g., invalid, missing, or unknown argument.
-4: Insufficient privileges.
+4
+ Insufficient privileges.
Examples
--------
-Auto-register two prefixes for any newly created on-demand face, except those that has
-source IP address in ``10.0.0.0/8`` network::
-
- nfd-autoreg --prefix=/app1/video --prefix=/app2/pictures -b 10.0.0.0/8
+``nfd-autoreg -i /app1/video -i /app2/pictures -b 10.0.0.0/8``
+ Auto-register two prefixes for any newly created on-demand faces, except those that
+ have their remote IP address in the 10.0.0.0/8 network.
diff --git a/docs/manpages/nfd-status-http-server.rst b/docs/manpages/nfd-status-http-server.rst
index 5dc4b0c..c7ee6f6 100644
--- a/docs/manpages/nfd-status-http-server.rst
+++ b/docs/manpages/nfd-status-http-server.rst
@@ -4,38 +4,52 @@
Synopsis
--------
-**nfd-status-http-server** [**-h**] [**-a** *IPADDR*] [**-p** *PORT*] [**-r**] [**-v**]
+| **nfd-status-http-server** [**-a**\|\ **\--address** *address*] [**-p**\|\ **\--port** *port*] \
+ [**-f**\|\ **\--workdir** *dir*] [**-r**\|\ **\--robots**] [**-v**\|\ **\--verbose**]
+| **nfd-status-http-server** **-h**\|\ **\--help**
+| **nfd-status-http-server** **-V**\|\ **\--version**
Description
-----------
-``nfd-status-http-server`` is a daemon that enables the retrieval of NFD's status over HTTP.
+:program:`nfd-status-http-server` is a daemon that enables the retrieval of NFD's status over HTTP.
Options
-------
-``-h``
- Show help message and exit.
+.. option:: -a <address>, --address <address>
-``-a <IPADDR>``
- HTTP server IP address (default is 127.0.0.1).
+ HTTP server IP address (default is 127.0.0.1).
-``-p <PORT>``
- HTTP server port number (default is 6380).
+.. option:: -p <port>, --port <port>
-``-r``
- Enable HTTP robots to crawl (disabled by default).
+ HTTP server port number (default is 6380).
-``-v``
- Verbose mode.
+.. option:: -f <dir>, --workdir <dir>
+
+ Set the server's working directory.
+
+.. option:: -r, --robots
+
+ Enable HTTP robots to crawl (disabled by default).
+
+.. option:: -v, --verbose
+
+ Enable verbose mode.
+
+.. option:: -h, --help
+
+ Print help message and exit.
+
+.. option:: -V, --version
+
+ Show version information and exit.
Examples
--------
-Start NFD's HTTP status server on all IPv4 interfaces, port 80 (requires root)::
+``nfd-status-http-server -a 0.0.0.0 -p 80``
+ Start NFD's HTTP status server on all IPv4 interfaces, port 80 (requires privileges).
- nfd-status-http-server -a 0.0.0.0 -p 80
-
-Start NFD's HTTP status server on all IPv6 interfaces, port 8000::
-
- nfd-status-http-server -a :: -p 8000
+``nfd-status-http-server -a :: -p 8000``
+ Start NFD's HTTP status server on all IPv6 interfaces, port 8000.
diff --git a/docs/manpages/nfd-status.rst b/docs/manpages/nfd-status.rst
index f140483..b056465 100644
--- a/docs/manpages/nfd-status.rst
+++ b/docs/manpages/nfd-status.rst
@@ -1,14 +1,18 @@
nfd-status
==========
-SYNOPSIS
+Synopsis
--------
-| nfd-status
-DESCRIPTION
+**nfd-status**
+
+Description
-----------
-**nfd-status** is an alias of **nfdc status report**, which prints a comprehensive report of NFD status.
-SEE ALSO
+:program:`nfd-status` is an alias of **nfdc status report**,
+which prints a comprehensive report of NFD status.
+
+See Also
--------
-nfdc-status(1)
+
+:manpage:`nfdc-status(1)`
diff --git a/docs/manpages/nfd.rst b/docs/manpages/nfd.rst
index a3ed42b..57db00c 100644
--- a/docs/manpages/nfd.rst
+++ b/docs/manpages/nfd.rst
@@ -4,45 +4,57 @@
Synopsis
--------
-**nfd** [**-h**] [**-V**] [**-c** *file*] [**-m**]
+| **nfd** [**-c**\|\ **\--config** *file*]
+| **nfd** **-h**\|\ **\--help**
+| **nfd** **-m**\|\ **\--modules**
+| **nfd** **-V**\|\ **\--version**
Description
-----------
-NFD forwarding daemon.
+NFD is a network forwarder that implements the Named Data Networking (NDN) protocol.
Options
-------
-``-c <path/to/nfd.conf>`` or ``--config <path/to/nfd.conf>``
- Specify the path to nfd configuration file (default: ``${SYSCONFDIR}/ndn/nfd.conf``).
+.. option:: -c <file>, --config <file>
-``-m`` or ``--modules``
- List available logging modules.
+ Specify the path to NFD's configuration file.
-``-h`` or ``--help``
- Print help message and exit.
+.. option:: -h, --help
-``-V`` or ``--version``
- Show version information and exit.
+ Print help message and exit.
-Exit status
+.. option:: -m, --modules
+
+ List available logging modules.
+
+.. option:: -V, --version
+
+ Show version information and exit.
+
+Exit Status
-----------
-0: No error.
+0
+ No error.
-1: An unspecified error occurred.
+1
+ An unspecified error occurred.
-2: Malformed command line, e.g., invalid, missing, or unknown argument.
+2
+ Malformed command line, e.g., invalid, missing, or unknown argument.
-4: Insufficient privileges.
+4
+ Insufficient privileges.
Examples
--------
-Start NFD forwarding daemon as super user and use a configuration file from the current
-working directory.
+``sudo nfd --config nfd.conf``
+ Start NFD as super user with a configuration file from the current directory.
-::
+See Also
+--------
- sudo nfd --config nfd.conf
+:manpage:`nfdc(1)`
diff --git a/docs/manpages/nfdc-cs.rst b/docs/manpages/nfdc-cs.rst
index 831dd7d..c231a7c 100644
--- a/docs/manpages/nfdc-cs.rst
+++ b/docs/manpages/nfdc-cs.rst
@@ -1,40 +1,49 @@
nfdc-cs
=======
-SYNOPSIS
+Synopsis
--------
-| nfdc cs [info]
-| nfdc cs config [capacity <CAPACITY>] [admit on|off] [serve on|off]
-| nfdc cs erase <PREFIX> [count <COUNT>]
-DESCRIPTION
+| **nfdc cs** [**info**]
+| **nfdc cs** **config** [**capacity** *CAPACITY*] [**admit** **on**\|\ **off**] [**serve** **on**\|\ **off**]
+| **nfdc cs** **erase** *PREFIX* [**count** *COUNT*]
+
+Description
-----------
+
The **nfdc cs info** command shows CS statistics information.
The **nfdc cs config** command updates CS configuration.
The **nfdc cs erase** command erases cached Data under a name prefix.
-OPTIONS
+Options
-------
-<CAPACITY>
+
+.. option:: <CAPACITY>
+
Maximum number of Data packets the CS can store.
Lowering the capacity causes the CS to evict excess Data packets.
-admit on|off
+.. option:: admit on|off
+
Whether the CS can admit new Data.
-serve on|off
+.. option:: serve on|off
+
Whether the CS can satisfy incoming Interests using cached Data.
Turning this off causes all CS lookups to miss.
-<PREFIX>
+.. option:: <PREFIX>
+
Name prefix of cached Data packets.
-<COUNT>
+.. option:: <COUNT>
+
Maximum number of cached Data packets to erase.
The default is "no limit".
-SEE ALSO
+See Also
--------
-nfd(1), nfdc(1)
+
+:manpage:`nfdc(1)`
diff --git a/docs/manpages/nfdc-face.rst b/docs/manpages/nfdc-face.rst
index 410b814..d9022af 100644
--- a/docs/manpages/nfdc-face.rst
+++ b/docs/manpages/nfdc-face.rst
@@ -1,20 +1,21 @@
nfdc-face
=========
-SYNOPSIS
+Synopsis
--------
-| nfdc face [list [[remote] <FACEURI>] [local <FACEURI>] [scheme <SCHEME>]]
-| nfdc face show [id] <FACEID>
-| nfdc face create [remote] <FACEURI> [[persistency] <PERSISTENCY>] [local <FACEURI>]
-| [reliability on|off] [congestion-marking on|off]
-| [congestion-marking-interval <MARKING-INTERVAL>]
-| [default-congestion-threshold <CONGESTION-THRESHOLD>]
-| [mtu <MTU>]
-| nfdc face destroy [face] <FACEID|FACEURI>
-| nfdc channel [list]
-DESCRIPTION
+| **nfdc face** [**list** [[**remote**] *FACEURI*] [**local** *FACEURI*] [**scheme** *SCHEME*]]
+| **nfdc face** **show** [**id**] *FACEID*
+| **nfdc face** **create** [**remote**] *FACEURI* [[**persistency**] *PERSISTENCY*] [**local** *FACEURI*]
+| [**mtu** *MTU*] [**reliability** **on**\|\ **off**] [**congestion-marking** **on**\|\ **off**]
+| [**congestion-marking-interval** *MARKING-INTERVAL*]
+| [**default-congestion-threshold** *CONGESTION-THRESHOLD*]
+| **nfdc face** **destroy** [**face**] *FACEID*\|\ *FACEURI*
+| **nfdc channel** [**list**]
+
+Description
-----------
+
In NFD, a face is the generalization of network interface.
It could be a physical network interface to communicate on a physical link,
an overlay communication channel between NFD and a remote node,
@@ -50,13 +51,16 @@
The **nfdc channel list** command shows a list of channels.
Channels are listening sockets that can accept incoming connections and create new faces.
-OPTIONS
+Options
-------
-<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>
+
A URI representing the remote or local endpoint of a face.
Examples:
@@ -71,9 +75,13 @@
- ether://[08:00:27:01:01:01]
- dev://eth0
- When a hostname is specified, a DNS query is used to obtain the IP address.
+ 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.
+ If a hostname is specified, :program:`nfdc` will perform a DNS resolution to obtain the
+ corresponding IP address.
-<SCHEME>
+.. option:: <SCHEME>
+
The scheme portion of either remote or local endpoint.
Examples:
@@ -81,75 +89,88 @@
- unix
- dev
-<PERSISTENCY>
+.. option:: <PERSISTENCY>
+
Either "persistent" or "permanent".
A "persistent" face (the default) is closed when a socket error occurs.
A "permanent" face survives socket errors, and is closed only with a **nfdc destroy** command.
-<MARKING-INTERVAL>
- The initial marking interval (in milliseconds) during an incident of congestion.
+.. option:: <MTU>
-<CONGESTION-THRESHOLD>
- This value serves two purposes:
- It is the maximum bound of the congestion threshold for the face, as well as the default
- threshold used if the face does not support retrieving the capacity of the send queue.
-
-<MTU>
The MTU used to override the MTU of the underlying transport on Ethernet and UDP faces.
This MTU serves as an upper bound for the MTU provided by the transport.
The range of acceptable values may be limited by the forwarder.
To unset this override, specify the MTU as "auto".
-EXIT CODES
-----------
-0: Success
+.. option:: <MARKING-INTERVAL>
-1: An unspecified error occurred
+ The initial marking interval (in milliseconds) during an incident of congestion.
-2: Malformed command line
+.. option:: <CONGESTION-THRESHOLD>
-3: Face not found (**nfdc face show** and **nfdc face destroy** only)
+ This value serves two purposes:
+ It is the maximum bound of the congestion threshold for the face, as well as the default
+ threshold used if the face does not support retrieving the capacity of the send queue.
-4: FaceUri canonization failed (**nfdc face create** and **nfdc face destroy** only)
+Exit Status
+-----------
-5: Ambiguous: multiple matching faces are found (**nfdc face destroy** only)
+0
+ Success.
-EXAMPLES
+1
+ An unspecified error occurred.
+
+2
+ Malformed command line.
+
+3
+ Face not found (**nfdc face show** and **nfdc face destroy** only).
+
+4
+ FaceUri canonization failed (**nfdc face create** and **nfdc face destroy** only).
+
+5
+ Ambiguous: multiple matching faces are found (**nfdc face destroy** only).
+
+Examples
--------
-nfdc face list
+
+``nfdc face list``
List all faces.
-nfdc face list scheme udp4
+``nfdc face list scheme udp4``
List all UDP-over-IPv4 faces.
-nfdc face show id 300
+``nfdc face show id 300``
Show information about the face whose FaceId is 300.
-nfdc face create remote udp://router.example.net
+``nfdc face create remote udp://router.example.net``
Create a face with the specified remote FaceUri, keeping all other settings at their defaults.
-nfdc face create remote ether://[08:00:27:01:01:01] local dev://eth2 persistency permanent
+``nfdc face create remote ether://[08:00:27:01:01:01] local dev://eth2 persistency permanent``
Create a face with the specified remote FaceUri, local FaceUri, and persistency.
-nfdc face create remote udp://router.example.net reliability on
+``nfdc face create remote udp://router.example.net reliability on``
Create a face with the specified remote FaceUri and enable NDNLP reliability.
-nfdc face create remote udp://router.example.net congestion-marking-interval 100 default-congestion-threshold 65536
+``nfdc face create remote udp://router.example.net congestion-marking-interval 100 default-congestion-threshold 65536``
Create a face with the specified remote FaceUri. Set the base congestion marking interval to
100 ms and the default congestion threshold to 65536 bytes.
-nfdc face create remote udp://router.example.net congestion-marking off
+``nfdc face create remote udp://router.example.net congestion-marking off``
Create a face with the specified remote FaceUri and explicitly disable congestion marking.
-nfdc face create remote udp://router.example.net mtu 4000
+``nfdc face create remote udp://router.example.net mtu 4000``
Create a face with the specified remote FaceUri and set the override MTU to 4000 bytes.
-nfdc face destroy 300
+``nfdc face destroy 300``
Destroy the face whose FaceId is 300.
-nfdc face destroy udp4://192.0.2.1:6363
+``nfdc face destroy udp4://192.0.2.1:6363``
Destroy the face whose remote FaceUri is "udp4://192.0.2.1:6363".
-SEE ALSO
+See Also
--------
-nfd(1), nfdc(1)
+
+:manpage:`nfdc(1)`
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)`
diff --git a/docs/manpages/nfdc-status.rst b/docs/manpages/nfdc-status.rst
index 3a1959b..5b26ce3 100644
--- a/docs/manpages/nfdc-status.rst
+++ b/docs/manpages/nfdc-status.rst
@@ -1,13 +1,15 @@
nfdc-status
===========
-SYNOPSIS
+Synopsis
--------
-| nfdc status [show]
-| nfdc status report [<FORMAT>]
-DESCRIPTION
+| **nfdc status** [**show**]
+| **nfdc status** **report** [*FORMAT*]
+
+Description
-----------
+
The **nfdc status show** command shows general status of NFD, including its version,
uptime, data structure counters, and global packet counters.
@@ -21,12 +23,19 @@
- CS statistics information (individually available from **nfdc cs info**)
- list of strategy choices (individually available from **nfdc strategy list**)
-OPTIONS
+Options
-------
-<FORMAT>
+
+.. option:: <FORMAT>
+
The format of NFD status report, either ``text`` or ``xml``.
The default is ``text``.
-SEE ALSO
+See Also
--------
-nfdc(1), nfdc-channel(1), nfdc-face(1), nfdc-fib(1), nfdc-route(1), nfdc-strategy(1)
+
+:manpage:`nfdc(1)`,
+:manpage:`nfdc-cs(1)`,
+:manpage:`nfdc-face(1)`,
+:manpage:`nfdc-route(1)`,
+:manpage:`nfdc-strategy(1)`
diff --git a/docs/manpages/nfdc-strategy.rst b/docs/manpages/nfdc-strategy.rst
index 93b0d45..e028df5 100644
--- a/docs/manpages/nfdc-strategy.rst
+++ b/docs/manpages/nfdc-strategy.rst
@@ -1,15 +1,17 @@
nfdc-strategy
=============
-SYNOPSIS
+Synopsis
--------
-| nfdc strategy [list]
-| nfdc strategy show [prefix] <PREFIX>
-| nfdc strategy set [prefix] <PREFIX> [strategy] <STRATEGY>
-| nfdc strategy unset [prefix] <PREFIX>
-DESCRIPTION
+| **nfdc strategy** [**list**]
+| **nfdc strategy** **show** [**prefix**] *PREFIX*
+| **nfdc strategy** **set** [**prefix**] *PREFIX* [**strategy**] *STRATEGY*
+| **nfdc strategy** **unset** [**prefix**] *PREFIX*
+
+Description
-----------
+
In NFD, packet forwarding behavior is determined by forwarding pipelines and forwarding strategies.
The forwarding pipelines define general steps of packet processing.
Forwarding strategies provide the intelligence to make decision on whether, when, and where
@@ -23,79 +25,90 @@
The **nfdc strategy show** command shows the effective strategy choice for a specific name.
The **nfdc strategy set** command sets the strategy for a name prefix.
-The strategy for ``"/"`` prefix is the default strategy.
+The strategy for the ``"/"`` prefix is the default strategy.
The **nfdc strategy unset** command clears the strategy choice at a name prefix,
so that a strategy choice at a shorter prefix or the default strategy will be used.
It undoes a prior **nfdc strategy set** command on the same name prefix.
-It is prohibited to unset the strategy choice for ``"/"`` prefix because there must always be a
-default strategy.
+It is prohibited to unset the strategy choice for the ``"/"`` prefix because there must always be
+a default strategy.
-OPTIONS
+Options
-------
-<PREFIX>
+
+.. option:: <PREFIX>
+
The name prefix of a strategy choice.
The strategy choice is effective for all Interests under the name prefix,
unless overridden by another strategy choice at a longer prefix.
-<STRATEGY>
+.. option:: <STRATEGY>
+
A name that identifies the forwarding strategy.
- Consult NFD Developer's Guide for a complete list of all implemented strategies.
+ Consult the NFD Developer's Guide for a complete list of all implemented strategies.
For the ASF, BestRoute, and Multicast strategies, the following options may be supplied
to configure exponential retransmission suppression by appending them after the strategy
name and version number.
- **retx-suppression-initial**
+ retx-suppression-initial
Starting duration of the suppression interval within which any retransmitted
Interests are considered for suppression. The default value is 10 ms.
Format: ``retx-suppression-initial~<milliseconds>``
- **retx-suppression-max**
+ retx-suppression-max
Maximum duration of the suppression interval. Must not be smaller than
**retx-suppression-initial**. The default value is 250 ms.
Format: ``retx-suppression-max~<milliseconds>``
- **retx-suppression-multiplier**
+ retx-suppression-multiplier
The suppression interval is increased by this multiplier. The default value is 2.
Format: ``retx-suppression-multiplier~<float>``
See :manpage:`nfd-asf-strategy(7)` for details on additional parameters for ASF strategy.
-EXIT CODES
-----------
-0: Success
+Exit Status
+-----------
-1: An unspecified error occurred
+0
+ Success.
-2: Malformed command line
+1
+ An unspecified error occurred.
-7: Strategy not found (**nfdc strategy set** only)
+2
+ Malformed command line.
-EXAMPLES
+7
+ Strategy not found (**nfdc strategy set** only).
+
+Examples
--------
-nfdc strategy list
+
+``nfdc strategy list``
List all configured strategy choices.
-nfdc strategy show prefix /localhost/ping/1
+``nfdc strategy show prefix /localhost/ping/1``
Identify which strategy will handle Interests named "/localhost/ping/1".
-nfdc strategy set prefix / strategy /localhost/nfd/strategy/best-route
+``nfdc strategy set prefix / strategy /localhost/nfd/strategy/best-route``
Set the default strategy to best-route, latest version.
-nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/multicast/v=4
+``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/multicast/v=4``
Set the strategy for the "/ndn" prefix to multicast, version 4.
-nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/multicast/v=4/retx-suppression-initial~20/retx-suppression-max~500
+``nfdc strategy set prefix /ndn strategy /localhost/nfd/strategy/multicast/v=4/retx-suppression-initial~20/retx-suppression-max~500``
Set the strategy for the "/ndn" prefix to multicast, version 4, with retransmission
suppression initial interval set to 20 ms and maximum interval set to 500 ms.
-nfdc strategy unset prefix /ndn
+``nfdc strategy unset prefix /ndn``
Clear the strategy choice for the "/ndn" prefix.
-SEE ALSO
+See Also
--------
-nfd(1), nfdc(1), nfd-asf-strategy(7)
+
+:manpage:`nfdc(1)`,
+:manpage:`nfd-asf-strategy(7)`
diff --git a/docs/manpages/nfdc.rst b/docs/manpages/nfdc.rst
index 1e77830..2e5d089 100644
--- a/docs/manpages/nfdc.rst
+++ b/docs/manpages/nfdc.rst
@@ -1,58 +1,74 @@
nfdc
====
-SYNOPSIS
+Synopsis
--------
-| nfdc COMMAND [ARGUMENTS] ...
-| nfdc help [COMMAND]
-| nfdc [-h|--help]
-| nfdc -V|--version
-| nfdc -f|--batch BATCH-FILE
-DESCRIPTION
+| **nfdc** *COMMAND* [*ARGUMENTS*]...
+| **nfdc** **help** [*COMMAND*]
+| **nfdc** [**-h**\|\ **\--help**]
+| **nfdc** **-V**\|\ **\--version**
+| **nfdc** **-f**\|\ **\--batch** *file*
+
+Description
-----------
-**nfdc** is a tool to manage a running instance of NFD.
-Features of nfdc are organized into subcommands.
-To print a list of all subcommands, run **nfdc** without arguments.
-To show how to use a subcommand, run **nfdc help** followed by the subcommand name.
+:program:`nfdc` is a command-line tool to manage a running instance of NFD.
-OPTIONS
+All features of :program:`nfdc` are organized into subcommands.
+To print a list of all subcommands, run ``nfdc`` without arguments.
+To show how to use a subcommand, run ``nfdc help`` followed by the subcommand name.
+
+Options
-------
-<COMMAND>
- A subcommand name.
- It usually contains a noun and a verb.
-<ARGUMENTS>
+.. option:: <COMMAND>
+
+ A subcommand name. It usually contains a noun and a verb.
+
+.. option:: <ARGUMENTS>
+
Arguments to the subcommand.
-``-h`` or ``--help``
+.. option:: -h, --help
+
Print a list of available subcommands and exit.
-``-V`` or ``--version``
+.. option:: -V, --version
+
Show version information and exit.
-``-f BATCH-FILE`` or ``--batch BATCH-FILE``
- Process arguments specified in the ``BATCH-FILE`` as if they would have appeared
- in the command line (but without ``nfdc``). When necessary, arguments should be
- escaped using backslash ``\``, single ``'``, or double quotes ``"``. If any of
- the command fails, the processing will be stopped at that command with error
- code 2. Empty lines and lines that start with ``#`` character will be ignored.
- Note that the batch file does not support empty string arguments
- (``""`` or ``''``), even if they are supported by the regular command line ``nfdc``.
+.. option:: -f <file>, --batch <file>
- When running a sequence of commands in rapid succession from a script, this
- option ensures that the commands are properly timestamped and can therefore
- be accepted by NFD.
+ Process the list of arguments specified in *file* as if they would have appeared on
+ the command line.
+ When running a sequence of commands in rapid succession from a script, this option
+ ensures that the commands are properly timestamped and can therefore be accepted
+ by NFD.
-EXAMPLES
+ When necessary, arguments should be escaped using a backslash (``\``), single quotes
+ (``'``), or double quotes (``"``).
+ If any of the commands fail, processing will stop at that command and :program:`nfdc`
+ will exit with error code 2.
+ Empty lines and lines that start with the ``#`` character are ignored.
+ Note that the batch file does not support empty string arguments (``""`` or ``''``),
+ even if they would normally be supported on the regular command line of :program:`nfdc`.
+
+Examples
--------
-nfdc
+
+``nfdc``
List all subcommands.
-nfdc help face create
+``nfdc help face create``
Show how to use the ``nfdc face create`` subcommand.
-SEE ALSO
+See Also
--------
-nfdc-status(1), nfdc-face(1), nfdc-route(1), nfdc-cs(1), nfdc-strategy(1)
+
+:manpage:`nfd(1)`,
+:manpage:`nfdc-cs(1)`,
+:manpage:`nfdc-face(1)`,
+:manpage:`nfdc-route(1)`,
+:manpage:`nfdc-status(1)`,
+:manpage:`nfdc-strategy(1)`