docs+ndnsec: improve description and parsing of command options, rewrite man pages
Replace custom redmine_issue extension with sphinx.ext.extlinks
Refs: #4907
Change-Id: Ib0cb94156ae4fc80cdcaf4c70d7c8d55c16fcbc3
diff --git a/docs/manpages/ndnsec-cert-dump.rst b/docs/manpages/ndnsec-cert-dump.rst
index 5aa69a9..04e0107 100644
--- a/docs/manpages/ndnsec-cert-dump.rst
+++ b/docs/manpages/ndnsec-cert-dump.rst
@@ -1,52 +1,50 @@
ndnsec-cert-dump
================
-``ndnsec-cert-dump`` is a tool to dump a certificate from **Public Info Base** or file and output
-it to standard output.
+Synopsis
+--------
-Usage
------
-
-::
-
- ndnsec-cert-dump [-h] [-p] [-ikf] name
+**ndnsec-cert-dump** [**-h**] [**-p**] [**-r** [**-H** *host*] [**-P** *port*]]
+[**-i**\|\ **-k**\|\ **-f**] *name*
Description
-----------
-``ndnsec-cert-dump`` can read a certificate from **Public Info Base (PIB)** or a file and output
-the certificate to standard output.
+:program:`ndnsec-cert-dump` reads a certificate from the **Public Info Base (PIB)**
+or from a file, and prints it on the standard output.
-By default, ``name`` is interpreted as a certificate name.
+By default, *name* is interpreted as a certificate name.
Options
-------
-``-i``
- Interpret ``name`` as an identity name. If specified, the certificate to dump is the default
- certificate of the identity.
+.. option:: -i, --identity
-``-k``
- Interpret ``name`` as a key name. If specified, the certificate to dump is the default certificate
- of the key.
+ Interpret *name* as an identity name. If specified, the certificate to dump
+ is the default certificate of the identity.
-``-f``
- Interpret ``name`` as a path to a file containing the certificate. If ``name`` is ``-``,
- certificate will be read from standard input.
+.. option:: -k, --key
-``-p``
- Print out the certificate to a human-readable format.
+ Interpret *name* as a key name. If specified, the certificate to dump is the
+ default certificate of the key.
-Examples
---------
+.. option:: -f, --file
-Dump a certificate from PIB to standard output:
-::
+ Interpret *name* as a path to a file containing the certificate. If *name*
+ is "-", the certificate will be read from the standard input.
+
+.. option:: -p, --pretty
+
+ Print the certificate in a human-readable format.
+
+Example
+-------
+
+Dump a certificate from PIB to standard output::
$ ndnsec-cert-dump /ndn/test/david/KEY/ksk-1396913058196/ID-CERT/%00%00%01E%3E%9D%A0%DE
-Dump a certificate to a human-readable format:
-::
+Dump a certificate in human-readable format::
$ ndnsec-cert-dump -p /ndn/test/david/KEY/ksk-1396913058196/ID-CERT/%00%00%01E%3E%9D%A0%DE
Certificate name:
diff --git a/docs/manpages/ndnsec-cert-gen.rst b/docs/manpages/ndnsec-cert-gen.rst
index 97e8e87..3b6617f 100644
--- a/docs/manpages/ndnsec-cert-gen.rst
+++ b/docs/manpages/ndnsec-cert-gen.rst
@@ -1,60 +1,64 @@
ndnsec-cert-gen
===============
-``ndnsec-cert-gen`` is a tool to issue an identity certificate.
+Synopsis
+--------
-Usage
------
-
-::
-
- ndnsec-cert-gen [-h] [-S timestamp] [-E timestamp] [-I info] [-s sign-id] [-i issuer-id] request
+**ndnsec-cert-gen** [**-h**] [**-S** *timestamp*] [**-E** *timestamp*]
+[**-I** *info*]... [**-s** *signer*] [**-i** *issuer*] *file*
Description
-----------
-``ndnsec-cert-gen`` takes signing request as input and issues an identity certificate for the key in
-the signing request. The signing request can be created during ``ndnsec-keygen`` and can be
-re-generated with ``ndnsec-sign-req``.
+: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`.
-By default, the default key/certificate will be used to sign the issued certificate.
+By default, the default key is used to sign the issued certificate.
-``request`` could be a path to a file that contains the signing request. If ``request`` is ``-``,
-then signing request will be read from 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 will be written to standard output in base64 encoding.
+The generated certificate is written to the standard output in base64 encoding.
Options
-------
-``-S timestamp``
- Timestamp when the certificate becomes valid. The default value is now.
+.. option:: -S <timestamp>, --not-before <timestamp>
-``-E timestamp``
- Timestamp when the certificate expires. The default value is one year from now.
+ Date and time when the certificate becomes valid, in "YYYYMMDDhhmmss" format.
+ The default value is now.
-``-I info``
- Other information to be included in the issued certificate. For example,
+.. 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.
+
+.. option:: -I <info>, --info <info>
+
+ Other information to be included in the issued certificate. For example::
-I "affiliation Some Organization" -I "homepage http://home.page/"
-``-s sign-id``
- Signing identity. The default key/certificate of ``sign-id`` will be used to sign the requested
- certificate. If this option is not specified, the system default identity will be used.
+.. option:: -s <signer>, --sign-id <signer>
-``-s issuer-id``
- Issuer's ID to be included as part of the issued certificate name. If not specified, "NA"
- value will be used
+ Signing identity. The default key/certificate of *signer* will be used to
+ sign the requested certificate. If this option is not specified, the system
+ default identity will be used.
-Examples
---------
+.. option:: -i <issuer>, --issuer-id <issuer>
+
+ Issuer's ID to be included in the issued certificate name. The default
+ value is "NA".
+
+Example
+-------
::
$ ndnsec-cert-gen -S 20140401000000 -E 20150331235959 -N "David"
- -I "2.5.4.10 'Some Organization'" -s /ndn/test sign_request.cert
+ -I "2.5.4.10 'Some Organization'" -s /ndn/test request.cert
Bv0C9wc9CANuZG4IBHRlc3QIA0tFWQgFZGF2aWQIEWtzay0xMzk2OTEzMDU4MTk2
CAdJRC1DRVJUCAgAAAFFPp2g3hQDGAECFf0BdjCCAXIwIhgPMjAxNDA0MDEwMDAw
MDBaGA8yMDE1MDMzMTIzNTk1OVowKDAMBgNVBCkTBURhdmlkMBgGA1UEChMRU29t
diff --git a/docs/manpages/ndnsec-cert-install.rst b/docs/manpages/ndnsec-cert-install.rst
index a1a98a3..dae8ee7 100644
--- a/docs/manpages/ndnsec-cert-install.rst
+++ b/docs/manpages/ndnsec-cert-install.rst
@@ -1,56 +1,50 @@
ndnsec-cert-install
===================
-``ndnsec-cert-install`` is a tool to install a certificate into **Public Information Base (PIB)**.
+Synopsis
+--------
-Usage
------
-
-::
-
- ndnsec-cert-install [-h] [-IKN] cert-source
+**ndnsec-cert-install** [**-h**] [**-I**\|\ **-K**\|\ **-N**] *file*
Description
-----------
-``ndnsec-cert-install`` can insert a certificate into PIB. By default, the installed certificate
-will be set as the default certificate of its corresponding identity and the identity is set as
-the system default identity.
+: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.
-``cert-source`` could be a filesystem path or an HTTP URL of a file containing to certificate to
-install or . If ``cert-file`` is ``-``, the certificate will be read from standard input.
+*file* can be a filesystem path or an HTTP URL of a file containing the certificate
+to install. If *file* is "-", the certificate will be read from the standard input.
Options
-------
-``-I``
- Set the certificate as the default certificate of its corresponding identity, but do not change
- the system default identity.
+.. option:: -I, --identity-default
-``-K``
- Set the certificate as the default certificate of its corresponding key, but do not change the
- corresponding identity's default key and the system default identity.
+ Set the certificate as the default certificate for the corresponding identity,
+ but do not change the user's default identity.
-``-N``
- Install the certificate but do not change any default settings.
+.. option:: -K, --key-default
-Examples
---------
+ Set the certificate as the default certificate for the corresponding key, but
+ do not change the identity's default key or the user's default identity.
-Install a certificate and set it as the system default certificate:
+.. option:: -N, --no-default
-::
+ Install the certificate but do not change any default settings.
+
+Example
+-------
+
+Install a certificate and set it as the default certificate::
$ ndnsec-cert-install cert_file.cert
-Install a certificate with HTTP URL and set it as the system default certificate:
-
-::
+Install a certificate via HTTP and set it as the default certificate::
$ ndnsec-install-cert "http://ndncert.domain.com/cert/get/my-certificate.ndncert"
-Install a certificate but do not change any default settings:
-
-::
+Install a certificate but do not change any default settings::
$ ndnsec-cert-install -N cert_file.cert
diff --git a/docs/manpages/ndnsec-delete.rst b/docs/manpages/ndnsec-delete.rst
index 3c808af..141aa0c 100644
--- a/docs/manpages/ndnsec-delete.rst
+++ b/docs/manpages/ndnsec-delete.rst
@@ -1,32 +1,32 @@
ndnsec-delete
=============
-``ndnsec-delete`` is a tool to delete security data from both **Public Info Base** and
-**Trusted Platform Module**.
+Synopsis
+--------
-Usage
------
-
-::
-
- ndnsec-delete [-h] [-kc] name
+**ndnsec-delete** [**-h**] [**-k**\|\ **-c**] *name*
Description
-----------
-By default, ``ndnsec-delete`` interpret ``name`` as an identity name. If an identity is deleted,
-all the keys and certificates belonging to the identity will be deleted as well. If a key is
-deleted, all the certificate belonging to the key will be deleted as well.
+:program:`ndnsec-delete` allows to delete security data from both the
+**Public Info Base (PIB)** and the **Trusted Platform Module (TPM)**.
+By default, :program:`ndnsec-delete` will interpret *name* 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.
Options
-------
-``-k``
- Interpret ``name`` as a key name and delete the key and its related data.
+.. option:: -k, --delete-key
-``-c``
- Interpret ``name`` as a certificate name and delete the certificate.
+ Interpret *name* as a key name and delete the key and its associated data.
+
+.. option:: -c, --delete-cert
+
+ Interpret *name* as a certificate name and delete the certificate.
Exit Status
-----------
@@ -35,11 +35,9 @@
If the entity to be deleted does not exist, the exit status is 1.
For other errors, the exit status is 2.
-Examples
---------
+Example
+-------
-Delete all data related to an identity:
-
-::
+Delete all data related to an identity::
$ ndnsec-delete /ndn/test/david
diff --git a/docs/manpages/ndnsec-export.rst b/docs/manpages/ndnsec-export.rst
index 7b51ad4..4d7e277 100644
--- a/docs/manpages/ndnsec-export.rst
+++ b/docs/manpages/ndnsec-export.rst
@@ -1,49 +1,39 @@
ndnsec-export
=============
-Usage
------
+Synopsis
+--------
-::
-
- ndnsec-export [-h] [-o output] identity
+**ndnsec-export** [**-h**] [**-o** *file*] [**-P** *passphrase*] *identity*
Description
-----------
-``ndnsec-export`` exports the default certificate of an identity and its private key as a file. It
-will ask for a passphrase to encrypt the private key. The output file can be imported again with
-``ndnsec-import`` command.
+:program:`ndnsec-export` exports the default certificate of *identity* 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`.
Options
-------
-``-h``
- Print a help message.
+.. option:: -o <file>, --output <file>
-``-o output``
- Write to an output file instead of the standard output.
+ Write to the specified output file instead of the standard output.
-``-P passphrase``
- Passphrase to use for the export. If not specified (or specified an empty passphrase), the
- user is interactively asked to input the passphrase on the terminal. Note that specifying
- passphrase via -P is insecure, as it can potentially end up in shell history, be visible in
- ps output, etc.
+.. option:: -P <passphrase>, --password <passphrase>
-``identity``
- The identity name.
+ Passphrase to use for the export. 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.
-Examples
---------
+Example
+-------
-Export an identity's default certificate and private key into a file:
-
-::
+Export an identity's default certificate and private key into a file::
$ ndnsec-export -o alice.ndnkey /ndn/test/alice
-Export an identity's default certificate and private key to the standard output:
-
-::
+Export an identity's default certificate and private key to the standard output::
$ ndnsec-export /ndn/test/alice
diff --git a/docs/manpages/ndnsec-get-default.rst b/docs/manpages/ndnsec-get-default.rst
index 54da09e..0a27dee 100644
--- a/docs/manpages/ndnsec-get-default.rst
+++ b/docs/manpages/ndnsec-get-default.rst
@@ -1,61 +1,56 @@
ndnsec-get-default
==================
-``ndnsec-get-default`` is a tool to display the default setting of a particular entity.
+Synopsis
+--------
-Usage
------
-
-::
-
- ndnsec-get-default [-h] [-kc] [-i identity|-K key] [-q]
+**ndnsec-get-default** [**-h**] [**-k**\|\ **-c**] [**-i** *identity*\|\ **-K** *key*] [**-q**]
Description
-----------
-Given a particular entity, ``ndnsec-get-default`` can display its default setting as specified in
-options. If ``identity`` is specified, the given entity becomes the identity. If ``key`` is
-specified, the given identity becomes the key. If no entity is specified, the command will take the
-system default identity as the given entity.
+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.
Options
-------
-``-k``
- Display the given entity's default key name.
+.. option:: -k, --default-key
-``-c``
- Display the given entity's default certificate name.
+ Display the chosen entity's default key name.
-``-i identity``
- Display default setting of the ``identity``
+.. option:: -c, --default-cert
-``-K key``
- Display default setting of the ``key``.
+ Display the chosen entity's default certificate name.
-``-q``
- Disable trailling new line character.
+.. option:: -i <identity>, --identity <identity>
-Examples
---------
+ Display default settings of *identity*.
-Display an identity's default key name.
+.. option:: -K <key>, --key <key>
-::
+ Display default settings of *key*.
+
+.. option:: -q, --quiet
+
+ Disable printing the trailing newline character.
+
+Example
+-------
+
+Display an identity's default key name::
$ ndnsec-get-default -k -i /ndn/test/alice
/ndn/test/alice/ksk-1394129695025
-Display an identity's default certificate name.
-
-::
+Display an identity's default certificate name::
$ 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.
-
-::
+Display a key's default certificate name::
$ ndnsec-get-default -c -K /ndn/test/alice/ksk-1394129695025
/ndn/test/KEY/alice/ksk-1394129695025/ID-CERT/%FD%01D%98%9A%F2%3F
diff --git a/docs/manpages/ndnsec-import.rst b/docs/manpages/ndnsec-import.rst
index 7dd02ed..7c25a6a 100644
--- a/docs/manpages/ndnsec-import.rst
+++ b/docs/manpages/ndnsec-import.rst
@@ -1,39 +1,33 @@
ndnsec-import
=============
-Usage
------
+Synopsis
+--------
-::
-
- ndnsec-import [-h] input
+**ndnsec-import** [**-h**] [**-P** *passphrase*] *file*
Description
-----------
-``ndnsec-import`` imports a certificate and private key from a file created by ``ndnsec-export``. It
-will ask for the passphrase used to encrypt the private key.
+: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.
+
+If *file* is "-", read from the standard input.
Options
-------
-``-h``
- Print a help message.
+.. option:: -P <passphrase>, --password <passphrase>
-``-P passphrase``
- Passphrase to use for the export. If not specified (or specified an empty passphrase), the
- user is interactively asked to input the passphrase on the terminal. Note that specifying
- passphrase via -P is insecure, as it can potentially end up in shell history, be visible in
- ps output, etc.
+ Passphrase to use for the export. 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.
-``input``
- Read from an input file. Specify ``-`` to read from the standard input.
+Example
+-------
-Examples
---------
-
-Import a certificate and private key from a file:
-
-::
+Import a certificate and private key from a file::
$ ndnsec-import alice.ndnkey
diff --git a/docs/manpages/ndnsec-key-gen.rst b/docs/manpages/ndnsec-key-gen.rst
index 304f189..0d68b86 100644
--- a/docs/manpages/ndnsec-key-gen.rst
+++ b/docs/manpages/ndnsec-key-gen.rst
@@ -1,38 +1,42 @@
ndnsec-key-gen
==============
-``ndnsec-key-gen`` is tool to generate a pair of key.
+Synopsis
+--------
-Usage
------
-
-::
-
- ndnsec-key-gen [-h] [-n] [-d] [-t keyType] identity
+**ndnsec-key-gen** [**-h**] [**-n**] [**-t** *type*] [**-k** *keyidtype*] *identity*
Description
-----------
-``ndnsec-key-gen`` creates a key pair for the specified ``identity`` and sets the key as the
-identity's default key. ``ndnsec-key-gen`` will also create a signing request for the generated key.
-The signing request will be written to standard output in base64 encoding.
+:program:`ndnsec-key-gen` generates a key pair for the specified *identity* and
+sets the generated public key as the identity's default key.
+:program:`ndnsec-key-gen` will also create a signing request for the generated key.
+The signing request will be written to the standard output in base64 encoding.
-By default, it will also set the identity as the system default identity.
+By default, it will also set the identity as the user's default identity.
Options
-------
-``-n``
- Do not set the identity as the system default identity.
+.. option:: -n, --not-default
- Note that if it is the first identity/key/certificate, then it will be
- set as default regardless of ``-n`` flag.
+ Do not set the identity as the user's default identity.
-``-t keyType``
- Specify the key type. ``r`` (default) for RSA key. ``e`` for ECDSA key.
+ Note that if no other identity/key/certificate exists, then the identity
+ will become the default regardless of this option.
-Examples
---------
+.. option:: -t <type>, --type <type>
+
+ Type of key to generate. "r" for RSA (default), "e" for ECDSA.
+
+.. option:: -k <keyidtype>, --keyid-type <keyidtype>
+
+ Type of KeyId for the generated key. "r" for 64-bit random number (default),
+ "h" for SHA256 of the public key.
+
+Example
+-------
::
diff --git a/docs/manpages/ndnsec-list.rst b/docs/manpages/ndnsec-list.rst
index a3de1a9..e0fde91 100644
--- a/docs/manpages/ndnsec-list.rst
+++ b/docs/manpages/ndnsec-list.rst
@@ -1,24 +1,20 @@
ndnsec-list
===========
-``ndnsec-list`` is a tool to display entities stored in **Public Information Base (PIB)**, such as
-identities, keys, and certificates.
+Synopsis
+--------
-Usage
------
-
-::
-
- ndnsec-list [-h] [-KkCc]
+**ndnsec-list** [**-h**] [**-k**\|\ **-c**]
Description
-----------
-``ndnsec-list`` lists names of all the entities according to the granularity specified in options
-(The default granularity is identity). The default entities will be marked with ``*`` in front of
-their names. For example:
+:program:`ndnsec-list` prints the names of all the entities stored in the
+**Public Information Base (PIB)**, such as identities, keys, and certificates,
+up to the given granularity level. By default, only the identity names are
+shown. The default entities will be marked with a "*" in front of their names.
-::
+For example::
$ ndnsec list
* /ndn/edu/ucla/cs/yingdi
@@ -26,24 +22,23 @@
/ndn/test/bob
/ndn/test/alice
-
Options
-------
-``-K, -k``
- Display key names for each identity. The key name with ``*`` in front is the default key name of
- the corresponding identity.
+.. option:: -k, --key
-``-C, -c``
- Display certificate names for each key. The certificate name with ``*`` in front is the default
- certificate name of the corresponding key.
+ Display key names for each identity. The key name with a "*" in front is
+ the default key name of the corresponding identity.
-Examples
---------
+.. option:: -c, --cert
-Display all the key names in PIB.
+ Display certificate names for each key. The certificate name with a "*"
+ in front is the default certificate name of the corresponding key.
-::
+Example
+-------
+
+Display all the key names in PIB::
$ ndnsec-list -k
* /ndn/edu/ucla/cs/yingdi
@@ -59,9 +54,7 @@
/ndn/test/alice
+->* /ndn/test/alice/ksk-1394129695025
-Display all the certificate names in PIB.
-
-::
+Display all the certificate names in PIB::
$ ndnsec-list -c
* /ndn/edu/ucla/cs/yingdi
diff --git a/docs/manpages/ndnsec-set-default.rst b/docs/manpages/ndnsec-set-default.rst
index 4af6ad9..05c6677 100644
--- a/docs/manpages/ndnsec-set-default.rst
+++ b/docs/manpages/ndnsec-set-default.rst
@@ -1,49 +1,43 @@
ndnsec-set-default
==================
-``ndnsec-set-default`` is a tool to change the default security settings.
+Synopsis
+--------
-Usage
------
-
-::
-
- ndnsec-set-default [-h] [-k|c] name
+**ndnsec-set-default** [**-h**] [**-k**\|\ **-c**] *name*
Description
-----------
-By default, ``ndnsec-set-default`` takes ``name`` as an identity name and sets the identity as the
-system default identity.
+:program:`ndnsec-set-default` allows changing the default security settings.
+
+Without any options, *name*, which must be an identity name, is set as the
+default identity for the current user.
Options
-------
-``-k``
- Set default key. ``name`` should be a key name, ``ndnsec-set-default`` can infer the corresponding
- identity and set the key as the identity's default key.
+.. option:: -k, --default-key
-``-c``
- Set default certificate. ``name`` should be a certificate name, ``ndnsec-set-default`` can
- infer the corresponding key name and set the certificate as the key's default certificate.
+ Set *name*, which must be a key name, as the default key for the
+ corresponding identity.
-Examples
---------
+.. option:: -c, --default-cert
-Set a key's default certificate:
+ Set *name*, which must be a certificate name, as the default certificate
+ for the corresponding key.
-::
+Example
+-------
+
+Set a key's default certificate::
$ ndnsec-set-default -c /ndn/test/KEY/alice/ksk-1394129695025/ID-CERT/%FD%01D%98%9A%F2%3F
-Set an identity's default key:
-
-::
+Set an identity's default key::
$ ndnsec-set-default -k /ndn/test/alice/ksk-1394129695025
-Set system default identity:
-
-::
+Set the user's default identity::
$ ndnsec-set-default /ndn/test/alice
diff --git a/docs/manpages/ndnsec-sign-req.rst b/docs/manpages/ndnsec-sign-req.rst
index 90a0694..d17ff3c 100644
--- a/docs/manpages/ndnsec-sign-req.rst
+++ b/docs/manpages/ndnsec-sign-req.rst
@@ -1,37 +1,35 @@
ndnsec-sign-req
===============
-``ndnsec-sign-req`` is a tool to generate a signing request for a particular key.
+Synopsis
+--------
-Usage
------
-
-::
-
- ndnsec-sign-req [-h] [-k] name
+**ndnsec-sign-req** [**-h**] [**-k**] *name*
Description
-----------
-The signing request of a key is actually a self-signed certificate. Given key's information,
-``ndnsec-sign-req`` looks up the key in PIB. If such a key exists, a self-signed certificate of the
-key, or its signing request, will be outputed to **stdout** with base64 encoding.
+:program:`ndnsec-sign-req` generates a signing request for a key.
-By default, ``name`` is interpreted as an identity name. ``ndnsec-sign-req`` will generate a
-signing request for the identity's default key.
+The signing request of a key is actually a self-signed certificate. Given the
+key's information, :program:`ndnsec-sign-req` looks up the key in the PIB.
+If such a key exists, a self-signed certificate for the key, i.e. its signing
+request, is written to the standard output in base64 encoding.
+
+By default, *name* is interpreted as an identity name, and the signing request
+will be generated for that identity's default key.
Options
-------
-``-k``
- Interpret ``name`` as a key name.
+.. option:: -k, --key
-Examples
---------
+ Interpret *name* as a key name, instead of an identity name.
-Create a signing request for an identity's default key.
+Example
+-------
-::
+Create a signing request for an identity's default key::
$ ndnsec-sign-req /ndn/test/david
Bv0DAAc9CANuZG4IBHRlc3QIBWRhdmlkCANLRVkIEWtzay0xMzk2OTk4Mzg5MjU3
@@ -52,10 +50,7 @@
0wHjvDS1cuIH2j6XveoUYapRjZXaEZqB/YoBwRqEYq2KVn/ol5knLM6FIISXXjxn
cIh62A==
-
-Create a signing request for a particular key.
-
-::
+Create a signing request for a particular key::
$ ndnsec-sign-req -k /ndn/test/david/ksk-1396913058196
Bv0DAAc9CANuZG4IBHRlc3QIBWRhdmlkCANLRVkIEWtzay0xMzk2OTEzMDU4MTk2
diff --git a/docs/manpages/ndnsec-unlock-tpm.rst b/docs/manpages/ndnsec-unlock-tpm.rst
index 175ba51..f5a8d92 100644
--- a/docs/manpages/ndnsec-unlock-tpm.rst
+++ b/docs/manpages/ndnsec-unlock-tpm.rst
@@ -1,17 +1,13 @@
ndnsec-unlock-tpm
=================
-``ndnsec-unlock-tpm`` is a tool to (temporarily) unlock the **Trusted Platform Module (TPM)** that
-manages private keys.
+Synopsis
+--------
-Usage
------
-
-::
-
- ndnsec-unlock-tpm [-h]
+ndnsec-unlock-tpm [**-h**]
Description
-----------
-``ndnsec-unlock-tpm`` will ask for password to unlock the TPM.
+:program:`ndnsec-unlock-tpm` can be used to (temporarily) unlock the
+**Trusted Platform Module (TPM)** that manages private keys.