docs: reformat man pages to improve consistency and readability

Change-Id: I4f9afbc73c365dfa31eb6cd1e4a48368b6a9064f

docs/conf.py

@@ -75,22 +75,24 @@ def addExtensionIfExists(extension: str):
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('manpages/nfd',            'nfd',              'the Named Data Networking Forwarding Daemon',          [], 1),
-    ('manpages/nfdc',           'nfdc',             'interact with NFD management from the command line',   [], 1),
-    ('manpages/nfdc-status',    'nfdc-status',      'show NFD status',                                      [], 1),
+    ('manpages/nfd',            'nfd',              'Named Data Networking Forwarding Daemon',              [], 1),
+    ('manpages/nfdc',           'nfdc',             'manage a running NFD from the command line',           [], 1),
+    ('manpages/nfdc-status',    'nfdc-status',      'show NFD\'s status',                                   [], 1),
     ('manpages/nfdc-face',      'nfdc-face',        'show and manipulate NFD\'s faces',                     [], 1),
     ('manpages/nfdc-route',     'nfdc-route',       'show and manipulate NFD\'s routes',                    [], 1),
     ('manpages/nfdc-cs',        'nfdc-cs',          'show and manipulate NFD\'s Content Store',             [], 1),
     ('manpages/nfdc-strategy',  'nfdc-strategy',    'show and manipulate NFD\'s strategy choices',          [], 1),
     ('manpages/nfd-status',     'nfd-status',       'show a comprehensive report of NFD\'s status',         [], 1),
-    ('manpages/nfd-status-http-server', 'nfd-status-http-server',   'NFD status HTTP server',               [], 1),
-    ('manpages/ndn-autoconfig-server',  'ndn-autoconfig-server',    'auto-configuration server for NDN',    [], 1),
-    ('manpages/ndn-autoconfig',         'ndn-autoconfig',           'auto-configuration client for NDN',    [], 1),
-    ('manpages/ndn-autoconfig.conf',    'ndn-autoconfig.conf',      'configuration file for ndn-autoconfig',    [], 5),
-    ('manpages/nfd-autoreg',            'nfd-autoreg',              'NFD automatic prefix registration daemon', [], 1),
-    ('manpages/nfd-asf-strategy',       'nfd-asf-strategy',         'NFD ASF strategy',                     [], 7),
+    ('manpages/nfd-status-http-server', 'nfd-status-http-server', 'NFD status HTTP server',                 [], 1),
+    ('manpages/nfd-autoreg',            'nfd-autoreg',            'NFD automatic prefix registration daemon', [], 1),
+    ('manpages/ndn-autoconfig',         'ndn-autoconfig',         'auto-configuration client for NDN',      [], 1),
+    ('manpages/ndn-autoconfig-server',  'ndn-autoconfig-server',  'auto-configuration server for NDN',      [], 1),
+    ('manpages/ndn-autoconfig.conf',    'ndn-autoconfig.conf',    'configuration file for ndn-autoconfig',  [], 5),
+    ('manpages/nfd-asf-strategy',       'nfd-asf-strategy',       'NFD ASF strategy',                       [], 7),
 ]
 
+man_show_urls = True
+
 
 # -- Misc options ------------------------------------------------------------
 

docs/manpages.rst

@@ -15,8 +15,8 @@ Man pages
    manpages/nfd-status
    manpages/nfd-status-http-server
    schema
+   manpages/nfd-autoreg
    manpages/ndn-autoconfig
    manpages/ndn-autoconfig.conf
    manpages/ndn-autoconfig-server
    local-prefix-discovery
-   manpages/nfd-autoreg

docs/manpages/ndn-autoconfig-server.rst

@@ -34,16 +34,20 @@ this block is the ``Uri`` for the HUB, preferably a UDP tunnel.
 ``-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 @@ Examples
 
     ndn-autoconfig-server -p /ndn/edu/ucla tcp://spurs.cs.ucla.edu
 
-See also
+See Also
 --------
 
-:ref:`ndn-autoconfig`
+:manpage:`ndn-autoconfig(1)`

docs/manpages/ndn-autoconfig.rst

@@ -172,18 +172,23 @@ Send a DNS query to find home hub.
 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`

docs/manpages/nfd-asf-strategy.rst

@@ -5,7 +5,7 @@ Synopsis
 --------
 
 **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 @@ next hops to learn their RTTs.
 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 @@ Options
 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)`

docs/manpages/nfd-autoreg.rst

@@ -4,66 +4,78 @@ nfd-autoreg
 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).
 
 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.

docs/manpages/nfd-status-http-server.rst

@@ -4,38 +4,52 @@ nfd-status-http-server
 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>
 
-Examples
---------
+    Set the server's working directory.
+
+.. option:: -r, --robots
+
+    Enable HTTP robots to crawl (disabled by default).
+
+.. option:: -v, --verbose
+
+    Enable verbose mode.
 
-Start NFD's HTTP status server on all IPv4 interfaces, port 80 (requires root)::
+.. option:: -h, --help
 
-    nfd-status-http-server -a 0.0.0.0 -p 80
+    Print help message and exit.
+
+.. option:: -V, --version
+
+    Show version information and exit.
+
+Examples
+--------
 
-Start NFD's HTTP status server on all IPv6 interfaces, port 8000::
+``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 :: -p 8000
+``nfd-status-http-server -a :: -p 8000``
+    Start NFD's HTTP status server on all IPv6 interfaces, port 8000.

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)`