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/conf.py b/docs/conf.py
index 82688a1..7e73680 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,37 +1,53 @@
# -*- coding: utf-8 -*-
#
-# NFD - Named Data Networking Forwarding Daemon documentation build configuration file, created by
-# sphinx-quickstart on Sun Apr 6 19:58:22 2014.
+# Configuration file for the Sphinx documentation builder.
#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
-import sys
-import os
-import re
+# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('.'))
+#
+import os
+import sys
+# sys.path.insert(0, os.path.abspath('.'))
-# -- General configuration ------------------------------------------------
+
+# -- Project information -----------------------------------------------------
+
+project = u'ndn-cxx: NDN C++ library with eXperimental eXtensions'
+copyright = u'Copyright © 2013-2019 Regents of the University of California.'
+author = u'Named Data Networking Project'
+
+# The short X.Y version
+#version = ''
+
+# The full version, including alpha/beta/rc tags
+#release = ''
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%Y-%m-%d'
+
+
+# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+#
+needs_sphinx = '1.1'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
+ 'sphinx.ext.extlinks',
'sphinx.ext.todo',
- 'redmine_issue',
]
def addExtensionIfExists(extension):
@@ -39,10 +55,8 @@
__import__(extension)
extensions.append(extension)
except ImportError:
- sys.stderr.write("Extension '%s' in not available. "
+ sys.stderr.write("Extension '%s' not found. "
"Some documentation may not build correctly.\n" % extension)
- sys.stderr.write("To install, use \n"
- " sudo pip install %s\n" % extension.replace('.', '-'))
if sys.version_info[0] >= 3:
addExtensionIfExists('sphinxcontrib.doxylink')
@@ -51,232 +65,99 @@
# if os.getenv('GOOGLE_ANALYTICS', None):
# addExtensionIfExists('sphinxcontrib.googleanalytics')
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
# The master toctree document.
master_doc = 'index'
-# General information about the project.
-project = u'ndn-cxx: NDN C++ library with eXperimental eXtensions'
-copyright = u'Copyright (c) 2013-2019 Regents of the University of California.'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#default_role = None
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
-
-
-# -- Options for HTML output ----------------------------------------------
+# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-# html_theme = 'default'
+#
html_theme = 'named_data_theme'
-# Theme options are theme-specific and customize the look and feel of a theme
-# further. For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['./']
-
-# The name for this set of Sphinx documents. If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar. Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
+html_theme_path = ['.']
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#html_extra_path = []
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it. The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-html_file_suffix = ".html"
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'ndn-cxx-docs'
-
-
-# -- Options for LaTeX output ---------------------------------------------
+# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+ # The paper size ('letterpaper' or 'a4paper').
+ #
+ # 'papersize': 'letterpaper',
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+ # The font size ('10pt', '11pt' or '12pt').
+ #
+ # 'pointsize': '10pt',
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+ # Additional stuff for the LaTeX preamble.
+ #
+ # 'preamble': '',
+
+ # Latex figure (float) alignment
+ #
+ # 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- ('index', 'ndn-cxx-docs.tex', u'NDN C++ library with eXperimental eXtensions',
- u'Named Data Networking Project', 'manual'),
+ ('index', 'ndn-cxx-docs.tex', u'NDN C++ library with eXperimental eXtensions',
+ author, 'manual'),
]
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-
-# -- Options for manual page output ---------------------------------------
+# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('manpages/ndnsec', 'ndnsec', 'NDN security toolkit', None, 1),
- ('manpages/ndnsec-cert-dump', 'ndnsec-cert-dump', 'export an NDN certificate', None, 1),
- ('manpages/ndnsec-cert-gen', 'ndnsec-cert-gen', 'create an NDN certificate for an identity', None, 1),
- ('manpages/ndnsec-cert-install', 'ndnsec-cert-install', 'import an NDN certificate from a file', None, 1),
- ('manpages/ndnsec-delete', 'ndnsec-delete', 'delete an NDN identity, key, or certificate', None, 1),
- ('manpages/ndnsec-export', 'ndnsec-export',
- 'export an NDN certificate and its private key to a file', None, 1),
- ('manpages/ndnsec-get-default', 'ndnsec-get-default',
- 'show the default NDN identity, key, and certificate for the current user', None, 1),
- ('manpages/ndnsec-import', 'ndnsec-import',
- 'import an NDN certificate and its private key from a file', None, 1),
- ('manpages/ndnsec-key-gen', 'ndnsec-key-gen',
- 'generate an NDN key for an identity', None, 1),
- ('manpages/ndnsec-list', 'ndnsec-list',
- 'list all known NDN identities, keys, and certificates', None, 1),
- ('manpages/ndnsec-set-default', 'ndnsec-set-default',
- 'change the default NDN identity, key, or certificate for the current user', None, 1),
- ('manpages/ndnsec-sign-req', 'ndnsec-sign-req', 'generate an NDN certificate signing request', None, 1),
- ('manpages/ndnsec-unlock-tpm', 'ndnsec-unlock-tpm', 'unlock the TPM', None, 1),
- ('manpages/ndn-client.conf', 'ndn-client.conf', 'configuration file for NDN platform', None, 5),
- ('manpages/ndn-log', 'ndn-log', 'ndn-cxx logging', None, 7),
+ ('manpages/ndnsec', 'ndnsec', 'NDN security toolkit', None, 1),
+ ('manpages/ndnsec-cert-dump', 'ndnsec-cert-dump', 'export an NDN certificate', None, 1),
+ ('manpages/ndnsec-cert-gen', 'ndnsec-cert-gen', 'create an NDN certificate for an identity', None, 1),
+ ('manpages/ndnsec-cert-install', 'ndnsec-cert-install', 'import an NDN certificate from a file', None, 1),
+ ('manpages/ndnsec-delete', 'ndnsec-delete', 'delete an NDN identity, key, or certificate', None, 1),
+ ('manpages/ndnsec-export', 'ndnsec-export', 'export an NDN certificate and its private key to a file', None, 1),
+ ('manpages/ndnsec-get-default', 'ndnsec-get-default', 'show the default NDN identity, key, and certificate for the current user', None, 1),
+ ('manpages/ndnsec-import', 'ndnsec-import', 'import an NDN certificate and its private key from a file', None, 1),
+ ('manpages/ndnsec-key-gen', 'ndnsec-key-gen', 'generate an NDN key for an identity', None, 1),
+ ('manpages/ndnsec-list', 'ndnsec-list', 'list all known NDN identities, keys, and certificates', None, 1),
+ ('manpages/ndnsec-set-default', 'ndnsec-set-default', 'change the default NDN identity, key, or certificate for the current user', None, 1),
+ ('manpages/ndnsec-sign-req', 'ndnsec-sign-req', 'generate an NDN certificate signing request', None, 1),
+ ('manpages/ndnsec-unlock-tpm', 'ndnsec-unlock-tpm', 'unlock the TPM', None, 1),
+ ('manpages/ndn-client.conf', 'ndn-client.conf', 'configuration file for NDN platform', None, 5),
+ ('manpages/ndn-log', 'ndn-log', 'ndn-cxx logging', None, 7),
]
-
# If true, show URL addresses after external links.
-man_show_urls = True
+#man_show_urls = True
-# ---- Custom options --------
+# -- Custom options ----------------------------------------------------------
doxylink = {
- 'ndn-cxx' : ('ndn-cxx.tag', 'doxygen/'),
+ 'ndn-cxx': ('ndn-cxx.tag', 'doxygen/'),
+}
+
+extlinks = {
+ 'issue': ('https://redmine.named-data.net/issues/%s', 'issue #'),
}
if os.getenv('GOOGLE_ANALYTICS', None):
googleanalytics_id = os.environ['GOOGLE_ANALYTICS']
googleanalytics_enabled = True
-
-# exclude_patterns = ['RELEASE_NOTES.rst']
-
-redmine_project_url = "https://redmine.named-data.net/"
diff --git a/docs/index.rst b/docs/index.rst
index 1749fef..dc3682b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,9 +1,9 @@
ndn-cxx: NDN C++ library with eXperimental eXtensions
=====================================================
-ndn-cxx is a C++14 library, implementing Named Data Networking (NDN) primitives
-that can be used to write various NDN applications. The library is currently
-being used by the following projects:
+**ndn-cxx** is a C++14 library implementing Named Data Networking (NDN) primitives
+that can be used to write various NDN applications. The library is currently being
+used by the following projects:
* `NFD - NDN Forwarding Daemon <https://github.com/named-data/NFD>`_
* `NLSR - Named-data Link-State Routing protocol <https://github.com/named-data/NLSR>`_
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.
diff --git a/docs/redmine_issue.py b/docs/redmine_issue.py
deleted file mode 100644
index 0df2b1f..0000000
--- a/docs/redmine_issue.py
+++ /dev/null
@@ -1,70 +0,0 @@
-# -*- Mode: python; py-indent-offset: 4; indent-tabs-mode: nil; coding: utf-8; -*-
-# Based on http://doughellmann.com/2010/05/09/defining-custom-roles-in-sphinx.html
-
-"""Integration of Sphinx with Redmine.
-"""
-
-from docutils import nodes, utils
-from docutils.parsers.rst.roles import set_classes
-
-def redmine_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
- """Link to a Redmine issue.
-
- Returns 2 part tuple containing list of nodes to insert into the
- document and a list of system messages. Both are allowed to be
- empty.
-
- :param name: The role name used in the document.
- :param rawtext: The entire markup snippet, with role.
- :param text: The text marked with the role.
- :param lineno: The line number where rawtext appears in the input.
- :param inliner: The inliner instance that called us.
- :param options: Directive options for customization.
- :param content: The directive content for customization.
- """
- try:
- issue_num = int(text)
- if issue_num <= 0:
- raise ValueError
- except ValueError:
- msg = inliner.reporter.error(
- 'Redmine issue number must be a number greater than or equal to 1; '
- '"%s" is invalid.' % text, line=lineno)
- prb = inliner.problematic(rawtext, rawtext, msg)
- return [prb], [msg]
- app = inliner.document.settings.env.app
- node = make_link_node(rawtext, app, 'issues', str(issue_num), options)
- return [node], []
-
-def make_link_node(rawtext, app, type, slug, options):
- """Create a link to a Redmine resource.
-
- :param rawtext: Text being replaced with link node.
- :param app: Sphinx application context
- :param type: Link type (issue, changeset, etc.)
- :param slug: ID of the thing to link to
- :param options: Options dictionary passed to role func.
- """
- #
- try:
- base = app.config.redmine_project_url
- if not base:
- raise AttributeError
- except AttributeError:
- raise ValueError('redmine_project_url configuration value is not set')
- #
- slash = '/' if base[-1] != '/' else ''
- ref = base + slash + type + '/' + slug + '/'
- set_classes(options)
- node = nodes.reference(rawtext, 'Issue #' + utils.unescape(slug), refuri=ref,
- **options)
- return node
-
-def setup(app):
- """Install the plugin.
-
- :param app: Sphinx application context.
- """
- app.add_role('issue', redmine_role)
- app.add_config_value('redmine_project_url', None, 'env')
- return