docs: ndnsec man pages improvements

* Add a "See Also" section to most pages * Streamline/clarify some sentences * Refresh a few examples Change-Id: I3e0b62ad01c06faac632a120cde22a8da472426e
named-data · Jun 22, 2024 · 102f057 · 102f057
1 parent 361e168
commit 102f057
Show file tree

Hide file tree

Showing 13 changed files with 260 additions and 188 deletions.
diff --git a/docs/manpages/ndnsec-cert-dump.rst b/docs/manpages/ndnsec-cert-dump.rst
@@ -4,14 +4,15 @@ ndnsec-cert-dump
 Synopsis
 --------
 
-**ndnsec-cert-dump** [**-h**] [**-p**] [**-r** [**-H** *host*] [**-P** *port*]]
+**ndnsec cert-dump** [**-h**] [**-p**] [**-r** [**-H** *host*] [**-P** *port*]]
 [**-i**\|\ **-k**\|\ **-f**] *name*
 
 Description
 -----------
 
-:program:`ndnsec-cert-dump` reads a certificate from the **Public Info Base (PIB)**
-or from a file, and prints it on the standard output in Base64 encoding.
+This command reads an NDN certificate, either from the **Public Information Base (PIB)**
+or from the specified file, and prints it on the standard output, either in Base64 encoding
+or in a human-readable format.
 
 By default, *name* is interpreted as a certificate name.
 
@@ -37,16 +38,23 @@ Options
 
    Print the certificate in a human-readable format.
 
-Example
--------
+Examples
+--------
 
-Dump a certificate from PIB to standard output::
+Export a certificate from the local PIB to the standard output with Base64 encoding::
 
-    $ ndnsec-cert-dump /ndn/test/david/KEY/ksk-1396913058196/ID-CERT/%00%00%01E%3E%9D%A0%DE
+    $ ndnsec cert-dump /ndn/test/david/KEY/%7FE%1C%18%D2%03%BD%3F/self/v=1719080300644
+    Bv0BOAcxCANuZG4IBHRlc3QIBWRhdmlkCANLRVkICH9FHBjSA70/CARzZWxmNggA
+    AAGQQSuwZBQJGAECGQQANu6AFVswWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQ8
+    7QbdgubF3IznydpZ8PuppHgVRufGsUMDvHpS8Rw93rAAsw+8aVcNmw94wzpALWzD
+    3femcs+qHaWoIOBOn26SFlIbAQMcIwchCANuZG4IBHRlc3QIBWRhdmlkCANLRVkI
+    CH9FHBjSA70//QD9Jv0A/g8yMDI0MDYyMlQxODE4MjD9AP8PMjA0NDA2MTdUMTgx
+    ODIwF0cwRQIhAPqG+GtIQlbcgB9ZFAGCKcO7DBMK+K3RinEAbzqKpFTcAiAp+D8L
+    z/S6nPNtSTGBBxr4cdUecjIHxKN6DoP3K1o2yg==
 
 Print the NDN testbed root certificate in human-readable format::
 
-    $ curl -A ndnsec -fsLS https://named-data.net/ndnsec/ndn-testbed-root.ndncert.x3.base64 | ndnsec-cert-dump -fp -
+    $ curl -A ndnsec -fsLS https://named-data.net/ndnsec/ndn-testbed-root.ndncert.x3.base64 | ndnsec cert-dump -fp -
     Certificate Name:
       /ndn/KEY/%EC%F1L%8EQ%23%15%E0/ndn/%FD%00%00%01u%E6%7F2%10
     Additional Description:
@@ -62,3 +70,9 @@ Print the NDN testbed root certificate in human-readable format::
       Signature Type: SignatureSha256WithEcdsa
       Key Locator: Name=/ndn/KEY/%EC%F1L%8EQ%23%15%E0
       Self-Signed: yes
+
+See Also
+--------
+
+:manpage:`ndnsec-cert-install(1)`,
+:manpage:`ndnsec-export(1)`
diff --git a/docs/manpages/ndnsec-cert-gen.rst b/docs/manpages/ndnsec-cert-gen.rst
@@ -4,23 +4,23 @@ ndnsec-cert-gen
 Synopsis
 --------
 
-**ndnsec-cert-gen** [**-h**] [**-S** *timestamp*] [**-E** *timestamp*]
+**ndnsec cert-gen** [**-h**] [**-S** *timestamp*] [**-E** *timestamp*]
 [**-I** *info*]... [**-s** *signer*] [**-i** *issuer*] *file*
 
 Description
 -----------
 
-:program:`ndnsec-cert-gen` takes a signing request as input and issues an
-identity certificate for the key in the signing request. The signing request
-can be created with :program:`ndnsec-key-gen` and can be re-generated with
-:program:`ndnsec-sign-req`.
+This command takes a signing request as input and issues an identity certificate for
+the key contained in the signing request.
+A signing request is generated automatically by :program:`ndnsec-key-gen` for any new
+key, or it can be manually created for an existing key with :program:`ndnsec-sign-req`.
 
-By default, the default key is used to sign the issued certificate.
+Unless specified otherwise, the default key is used to sign the issued certificate.
 
-*file* is the name of a file that contains the signing request. If *file* is
-"-", the signing request is read from the standard input.
+*file* is the name of a file that contains the signing request.
+If *file* is "-", the signing request is read from the standard input.
 
-The generated certificate is written to the standard output in base64 encoding.
+The generated certificate is written to the standard output in Base64 encoding.
 
 Options
 -------
@@ -33,7 +33,7 @@ Options
 .. option:: -E <timestamp>, --not-after <timestamp>
 
    Date and time when the certificate expires, in "YYYYMMDDhhmmss" format.
-   The default value is 365 days after the **--not-before** timestamp.
+   The default value is 365 days after the :option:`--not-before` timestamp.
 
 .. option:: -I <info>, --info <info>
 
@@ -57,12 +57,12 @@ Options
    Issuer's ID to be included in the issued certificate name. The default
    value is "NA".
 
-Example
--------
+Examples
+--------
 
 ::
 
-    $ ndnsec-cert-gen -S 20200501000000 -E 20210101000000 -I "affiliation Some Organization" -I "foobar Foo Bar" -i "Universe" -s /ndn/test request.cert > signed.cert
+    $ ndnsec cert-gen -S 20200501000000 -E 20210101000000 -I "affiliation Some Organization" -I "foobar Foo Bar" -i "Universe" -s /ndn/test request.cert > signed.cert
 
     $ cat signed.cert
     Bv0BcgctCAdleGFtcGxlCANLRVkICOQUmX8oloLrCAhVbml2ZXJzZQgJ/QAAAXHR
@@ -74,7 +74,7 @@ Example
     YXL9AgIHRm9vIEJhchdHMEUCIQDPT9Hq1kvkE0r9W1aYSBVTnHlTEzgtz+v1DwkC
     ug/vLAIgY3xJITCwf55sqey33q5GIQSk1TRCkNNl58ojvPs5sNU=
 
-    $ ndnsec-cert-dump -p -f signed.cert
+    $ ndnsec cert-dump -p -f signed.cert
     Certificate Name:
       /example/KEY/%E4%14%99%7F%28%96%82%EB/Universe/%FD%00%00%01q%D1%02N%82
     Additional Description:
@@ -90,3 +90,11 @@ Example
     Signature Information:
       Signature Type: SignatureSha256WithEcdsa
       Key Locator: Name=/ndn/test/KEY/I%3FS%9A%28%BB%9A%95
+
+See Also
+--------
+
+:manpage:`ndnsec-cert-dump(1)`,
+:manpage:`ndnsec-cert-install(1)`,
+:manpage:`ndnsec-key-gen(1)`,
+:manpage:`ndnsec-sign-req(1)`
diff --git a/docs/manpages/ndnsec-cert-install.rst b/docs/manpages/ndnsec-cert-install.rst
@@ -4,15 +4,14 @@ ndnsec-cert-install
 Synopsis
 --------
 
-**ndnsec-cert-install** [**-h**] [**-I**\|\ **-K**\|\ **-N**] *file*
+**ndnsec cert-install** [**-h**] [**-I**\|\ **-K**\|\ **-N**] *file*
 
 Description
 -----------
 
-:program:`ndnsec-cert-install` allows importing a certificate into the
-**Public Information Base (PIB)**. By default, the installed certificate
-will be set as the default certificate for the corresponding identity and
-the identity will be set as the user's default identity.
+This command allows importing a certificate into the **Public Information Base (PIB)**.
+By default, the installed certificate will be set as the default certificate for the
+corresponding identity and the identity will be set as the user's default identity.
 
 *file* is a path to a file that contains the certificate to install.
 If *file* is "-", the certificate will be read from the standard input.
@@ -35,13 +34,20 @@ Options
 
    Install the certificate but do not change any default settings.
 
-Example
--------
+Examples
+--------
 
 Install a certificate and set it as the default certificate::
 
-    $ ndnsec-cert-install cert_file.cert
+    $ ndnsec cert-install cert_file.cert
 
 Install a certificate but do not change any default settings::
 
-    $ ndnsec-cert-install -N cert_file.cert
+    $ ndnsec cert-install -N cert_file.cert
+
+See Also
+--------
+
+:manpage:`ndnsec-cert-dump(1)`,
+:manpage:`ndnsec-cert-gen(1)`,
+:manpage:`ndnsec-import(1)`
diff --git a/docs/manpages/ndnsec-delete.rst b/docs/manpages/ndnsec-delete.rst
@@ -4,15 +4,15 @@ ndnsec-delete
 Synopsis
 --------
 
-**ndnsec-delete** [**-h**] [**-k**\|\ **-c**] *name*
+**ndnsec delete** [**-h**] [**-k**\|\ **-c**] *name*
 
 Description
 -----------
 
-:program:`ndnsec-delete` allows to delete security data from both the
-**Public Info Base (PIB)** and the **Trusted Platform Module (TPM)**.
+This command allows deleting security data from both the
+**Public Information Base (PIB)** and the **Trusted Platform Module (TPM)**.
 
-By default, :program:`ndnsec-delete` will interpret *name* as an identity name.
+By default, *name* is interpreted as an identity name.
 If an identity is deleted, all keys and certificates belonging to that identity
 will be deleted as well. If a key is deleted, all certificates associated with
 that key will be deleted as well.
@@ -33,11 +33,16 @@ Exit Status
 
 Normally, the exit status is 0 if the requested entity is deleted successfully.
 If the entity to be deleted does not exist, the exit status is 1.
-For other errors, the exit status is 2.
+For any other errors, the exit status is 2.
 
-Example
--------
+Examples
+--------
+
+Delete all data related to the identity ``/ndn/test/david``::
 
-Delete all data related to an identity::
+    $ ndnsec delete /ndn/test/david
+
+See Also
+--------
 
-    $ ndnsec-delete /ndn/test/david
+:manpage:`ndnsec-list(1)`
diff --git a/docs/manpages/ndnsec-export.rst b/docs/manpages/ndnsec-export.rst
@@ -4,27 +4,31 @@ ndnsec-export
 Synopsis
 --------
 
-**ndnsec-export** [**-h**] [**-o** *file*] [**-P** *passphrase*]
+**ndnsec export** [**-h**] [**-o** *file*] [**-P** *passphrase*]
 [**-i**\|\ **-k**\|\ **-c**] *name*
 
 Description
 -----------
 
-:program:`ndnsec-export` exports a certificate from the **Public Info Base (PIB)** and
-its private key to a file. It will ask for a passphrase to encrypt the private key.
-The resulting file can be imported again using :program:`ndnsec-import`.
+Export a certificate from the local **Public Information Base (PIB)** and its private key to
+a file in **SafeBag** format.
+The command will interactively ask for a passphrase to be used for encrypting the private key.
+
+The resulting file can be later imported using :program:`ndnsec-import`.
 
 Options
 -------
 
 .. option:: -i, --identity
 
-   Interpret *name* as an identity name. The default certificate of the identity will be exported.
-   This is the default unless **-k** or **-c** is specified.
+   Interpret *name* as an identity name.
+   The default certificate of the identity will be exported.
+   This is the default unless :option:`-k` or :option:`-c` is specified.
 
 .. option:: -k, --key
 
-   Interpret *name* as a key name. The default certificate of the key will be exported.
+   Interpret *name* as a key name.
+   The default certificate of the key will be exported.
 
 .. option:: -c, --cert
 
@@ -36,18 +40,24 @@ Options
 
 .. option:: -P <passphrase>, --password <passphrase>
 
-   Passphrase to use for the export. If empty or not specified, the user is
+   Passphrase to use for encryption. If empty or not specified, the user is
    interactively asked to type the passphrase on the terminal. Note that
    specifying the passphrase via this option is insecure, as it can potentially
    end up in the shell's history, be visible in :command:`ps` output, and so on.
 
-Example
--------
+Examples
+--------
 
-Export an identity's default certificate and private key into a file::
+Export an identity's default certificate and private key to a file::
 
-    $ ndnsec-export -o alice.ndnkey /ndn/test/alice
+    $ ndnsec export -o alice.ndnkey /ndn/test/alice
 
 Export a specific certificate and its private key to the standard output::
 
-    $ ndnsec-export -c /ndn/edu/ucla/alice/KEY/1%5D%A7g%90%B2%CF%AA/self/%FD%00%00%01r-%D3%DC%2A
+    $ ndnsec export -c /ndn/edu/ucla/alice/KEY/1%5D%A7g%90%B2%CF%AA/self/%FD%00%00%01r-%D3%DC%2A
+
+See Also
+--------
+
+:manpage:`ndnsec-cert-dump(1)`,
+:manpage:`ndnsec-import(1)`
diff --git a/docs/manpages/ndnsec-get-default.rst b/docs/manpages/ndnsec-get-default.rst
@@ -4,15 +4,17 @@ ndnsec-get-default
 Synopsis
 --------
 
-**ndnsec-get-default** [**-h**] [**-k**\|\ **-c**] [**-i** *identity*\|\ **-K** *key*] [**-q**]
+**ndnsec get-default** [**-h**] [**-k**\|\ **-c**] [**-i** *identity*\|\ **-K** *key*]
+[**-q**]
 
 Description
 -----------
 
-Given a particular entity, :program:`ndnsec-get-default` shows its default settings
-according to the command-line options. By default, if neither **-i** nor **-K** is
-given, the command displays the default identity or the default key/certificate of
-the default identity.
+This command shows the default settings of the local **Public Information Base (PIB)**
+or those of a specific PIB identity or key.
+
+By default, if neither :option:`-i` nor :option:`-K` is given, the command displays
+the default identity or the default key/certificate of the default identity.
 
 Options
 -------
@@ -37,20 +39,26 @@ Options
 
    Disable printing the trailing newline character.
 
-Example
--------
+Examples
+--------
 
 Display an identity's default key name::
 
-    $ ndnsec-get-default -k -i /ndn/test/alice
+    $ ndnsec get-default -k -i /ndn/test/alice
     /ndn/test/alice/ksk-1394129695025
 
 Display an identity's default certificate name::
 
-    $ ndnsec-get-default -c -i /ndn/test/alice
+    $ ndnsec get-default -c -i /ndn/test/alice
     /ndn/test/KEY/alice/ksk-1394129695025/ID-CERT/%FD%01D%98%9A%F2%3F
 
 Display a key's default certificate name::
 
-    $ ndnsec-get-default -c -K /ndn/test/alice/ksk-1394129695025
+    $ ndnsec get-default -c -K /ndn/test/alice/ksk-1394129695025
     /ndn/test/KEY/alice/ksk-1394129695025/ID-CERT/%FD%01D%98%9A%F2%3F
+
+See Also
+--------
+
+:manpage:`ndnsec-list(1)`,
+:manpage:`ndnsec-set-default(1)`
diff --git a/docs/manpages/ndnsec-import.rst b/docs/manpages/ndnsec-import.rst
@@ -4,30 +4,36 @@ ndnsec-import
 Synopsis
 --------
 
-**ndnsec-import** [**-h**] [**-P** *passphrase*] *file*
+**ndnsec import** [**-h**] [**-P** *passphrase*] *file*
 
 Description
 -----------
 
-:program:`ndnsec-import` imports a certificate and its private key from a file
-created by :program:`ndnsec-export`. It will ask for the passphrase used to
-encrypt the private key.
+Import a certificate and its private key from a file in **SafeBag** format.
+The command will interactively ask for a passphrase to be used for decrypting the private key.
+If *file* is "-", the **SafeBag** data will be read from the standard input.
 
-If *file* is "-", read from the standard input.
+:program:`ndnsec-export` can be used to create a file in the expected format.
 
 Options
 -------
 
 .. option:: -P <passphrase>, --password <passphrase>
 
-   Passphrase to use for the export. If empty or not specified, the user is
+   Passphrase to use for decryption. If empty or not specified, the user is
    interactively asked to type the passphrase on the terminal. Note that
    specifying the passphrase via this option is insecure, as it can potentially
    end up in the shell's history, be visible in :command:`ps` output, and so on.
 
-Example
--------
+Examples
+--------
 
 Import a certificate and private key from a file::
 
-    $ ndnsec-import alice.ndnkey
+    $ ndnsec import alice.ndnkey
+
+See Also
+--------
+
+:manpage:`ndnsec-cert-install(1)`,
+:manpage:`ndnsec-export(1)`