docs: fix linking to ndnsec-* man pages
And various other minor improvements
Change-Id: Idac7629ce2728ddb641bacfc020314ae3d7f00b9
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index bedf609..33ac6ce 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -78,7 +78,7 @@
Optional
~~~~~~~~
-To build tutorials, manpages, and API documentation the following additional dependencies
+To build tutorials, man pages, and API documentation the following additional dependencies
need to be installed:
- doxygen
@@ -278,9 +278,9 @@
# Only API docs in build/docs/doxygen
./waf doxygen
-If ``sphinx-build`` is detected during ``./waf configure``, manpages will automatically
+If ``sphinx-build`` is detected during ``./waf configure``, man pages will automatically
be built and installed during the normal build process (i.e., during ``./waf`` and
-``./waf install``). By default, manpages will be installed into ``${PREFIX}/share/man``
+``./waf install``). By default, man pages will be installed into ``${PREFIX}/share/man``
(the default value for ``PREFIX`` is ``/usr/local``). This location can be changed
during the ``./waf configure`` stage using the ``--prefix``, ``--datarootdir``, or
``--mandir`` options.
diff --git a/docs/manpages.rst b/docs/manpages.rst
index c88228e..7f01d30 100644
--- a/docs/manpages.rst
+++ b/docs/manpages.rst
@@ -1,20 +1,10 @@
-Manpages
-========
+Man pages
+=========
.. toctree::
- ndn-client.conf <manpages/ndn-client.conf>
- ndn-cxx logging <manpages/ndn-log>
- manpages/ndnsec
- ndnsec-list <manpages/ndnsec-list>
- ndnsec-get-default <manpages/ndnsec-get-default>
- ndnsec-set-default <manpages/ndnsec-set-default>
- ndnsec-key-gen <manpages/ndnsec-key-gen>
- ndnsec-sign-req <manpages/ndnsec-sign-req>
- ndnsec-cert-gen <manpages/ndnsec-cert-gen>
- ndnsec-cert-install <manpages/ndnsec-cert-install>
- ndnsec-cert-dump <manpages/ndnsec-cert-dump>
- ndnsec-delete <manpages/ndnsec-delete>
- ndnsec-export <manpages/ndnsec-export>
- ndnsec-import <manpages/ndnsec-import>
- ndnsec-unlock-tpm <manpages/ndnsec-unlock-tpm>
+ :glob:
:maxdepth: 1
+
+ ndn-client.conf <manpages/ndn-client.conf>
+ ndn-log: ndn-cxx logging <manpages/ndn-log>
+ manpages/ndnsec*
diff --git a/docs/manpages/ndn-client.conf.rst b/docs/manpages/ndn-client.conf.rst
index a2bd6fc..f3d8500 100644
--- a/docs/manpages/ndn-client.conf.rst
+++ b/docs/manpages/ndn-client.conf.rst
@@ -1,6 +1,9 @@
client.conf
===========
+Description
+-----------
+
System configuration of NDN platform is specified in ``client.conf``.
The configuration file ``client.conf`` is looked up in several directories in the following order:
@@ -13,11 +16,11 @@
Here is an example of ``client.conf`` for the current ndn-cxx package:
.. literalinclude:: ../../client.conf.sample
- :language: ini
+ :language: ini
-NFD
----
+Forwarder
+---------
transport
FaceUri for default connection toward local NDN forwarder. Only ``unix``, ``tcp``, ``tcp4``, and
@@ -38,17 +41,17 @@
pib=[scheme]:[location]
- Possible values for ``[scheme]``:
+ Possible values for ``[scheme]`` are:
- * ``pib-sqlite3``: local PIB implementation with SQLite3 storage engine
+ * ``pib-sqlite3``: local PIB implementation using the SQLite3 storage engine.
Possible values for ``[location]``:
- * absolute path where SQLite3 database will be stored
- * relative path (relative to ``config.conf``)
- * empty: default path ``$HOME/.ndn`` will be used
+ * absolute path where the SQLite3 database will be stored
+ * relative path (relative to ``client.conf``)
+ * empty: the default path ``$HOME/.ndn`` will be used
- When ``[location]`` is empty, trailing ``:`` can be omitted. For example::
+ When ``[location]`` is empty, the trailing ``:`` can be omitted. For example::
pib=pib-sqlite3
@@ -70,12 +73,12 @@
tpm=[scheme]:[location]
- Possible values for ``[scheme]``:
+ Possible values for ``[scheme]`` are:
* ``tpm-osx-keychain`` (default on macOS): secure storage of private keys in the macOS
Keychain with OS-provided access restrictions.
- ``[location]`` parameter is ignored.
+ The ``[location]`` parameter is ignored.
May not work for daemon applications, as user interaction may be required to access the
macOS Keychain.
@@ -86,10 +89,10 @@
* absolute path to directory that will store private/public key files (unencrypted with
``0700`` permission)
- * relative path (relative to ``config.conf``)
- * empty: default path ``$HOME/.ndn/ndnsec-tpm-file`` will be used
+ * relative path (relative to ``client.conf``)
+ * empty: the default path ``$HOME/.ndn/ndnsec-tpm-file`` will be used
- When ``[location]`` is empty, trailing ``:`` can be omitted. For example::
+ When ``[location]`` is empty, the trailing ``:`` can be omitted. For example::
tpm=tpm-file
diff --git a/docs/manpages/ndn-log.rst b/docs/manpages/ndn-log.rst
index 0a88f3e..f47dd1a 100644
--- a/docs/manpages/ndn-log.rst
+++ b/docs/manpages/ndn-log.rst
@@ -1,5 +1,8 @@
-ndn-log
-=======
+ndn-cxx logging
+===============
+
+Description
+-----------
The ndn-cxx logging facility exposes the internal state of NDN libraries and
applications so the user can investigate internal interactions, such as interest
@@ -8,8 +11,8 @@
user is able to specify the types of messages he or she would like to receive from
a set of logging modules pre-configured by library and application developers.
-Environment Variable
---------------------
+Environment
+-----------
One way to control ndn-cxx logging facility is through the environment variable
``NDN_LOG``. Using this variable, one can set the log levels for the available logging
diff --git a/docs/manpages/ndnsec.rst b/docs/manpages/ndnsec.rst
index 1eb0ed8..d65c3a7 100644
--- a/docs/manpages/ndnsec.rst
+++ b/docs/manpages/ndnsec.rst
@@ -21,51 +21,40 @@
Commands
--------
-list_
+The following commands are understood:
+
+:doc:`list <ndnsec-list>`
List all known identities/keys/certificates.
-get-default_
+:doc:`get-default <ndnsec-get-default>`
Show the default identity/key/certificate.
-set-default_
+:doc:`set-default <ndnsec-set-default>`
Change the default identity/key/certificate.
-delete_
+:doc:`delete <ndnsec-delete>`
Delete an identity/key/certificate.
-key-gen_
+:doc:`key-gen <ndnsec-key-gen>`
Generate a key for an identity.
-sign-req_
+:doc:`sign-req <ndnsec-sign-req>`
Generate a certificate signing request.
-cert-gen_
+:doc:`cert-gen <ndnsec-cert-gen>`
Create a certificate for an identity.
-cert-dump_
+:doc:`cert-dump <ndnsec-cert-dump>`
Export a certificate.
-cert-install_
+:doc:`cert-install <ndnsec-cert-install>`
Import a certificate from a file.
-export_
+:doc:`export <ndnsec-export>`
Export an identity as a SafeBag.
-import_
+:doc:`import <ndnsec-import>`
Import an identity from a SafeBag.
-unlock-tpm_
+:doc:`unlock-tpm <ndnsec-unlock-tpm>`
Unlock the TPM.
-
-.. _list: ndnsec-list.html
-.. _get-default: ndnsec-get-default.html
-.. _set-default: ndnsec-set-default.html
-.. _delete: ndnsec-delete.html
-.. _key-gen: ndnsec-key-gen.html
-.. _sign-req: ndnsec-sign-req.html
-.. _cert-gen: ndnsec-cert-gen.html
-.. _cert-dump: ndnsec-cert-dump.html
-.. _cert-install: ndnsec-cert-install.html
-.. _export: ndnsec-export.html
-.. _import: ndnsec-import.html
-.. _unlock-tpm: ndnsec-unlock-tpm.html