docs: fix syntax highlighting of code blocks
And various other cleanups
Change-Id: If945f5407036e73db980cafd2185359a488a0ff1
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index f893d1a..c02016f 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -8,7 +8,7 @@
following platforms:
- Ubuntu 18.04 (amd64, armhf, i386)
-- Ubuntu 19.10 (amd64)
+- Ubuntu 20.04 (amd64)
- macOS 10.13
- macOS 10.14
- macOS 10.15
@@ -40,19 +40,19 @@
To build ndn-cxx from source, one must first install a C++ compiler and all necessary
development tools and libraries:
-- Ubuntu
+- On **Ubuntu**
In a terminal, enter::
sudo apt install g++ pkg-config python3-minimal libboost-all-dev libssl-dev libsqlite3-dev
-- CentOS and Fedora
+- On **CentOS** and **Fedora**
In a terminal, enter::
sudo dnf install gcc-c++ pkgconf-pkg-config python3 boost-devel openssl-devel sqlite-devel
-- macOS
+- On **macOS**
* Install either Xcode (from the App Store) or the Command Line Tools
(with ``xcode-select --install``)
@@ -61,12 +61,12 @@
brew install boost openssl pkg-config
- .. note::
+ .. warning::
If a major OS upgrade is performed after installing the dependencies
with Homebrew, remember to reinstall all packages.
-- FreeBSD
+- On **FreeBSD**
In a terminal, enter::
@@ -80,28 +80,36 @@
- doxygen
- graphviz
-- sphinx
+- sphinx >= 1.3
- sphinxcontrib-doxylink
The following lists the steps to install these prerequisites on various common platforms.
-- On Ubuntu::
+- On **Ubuntu**:
+
+ .. code-block:: sh
sudo apt install doxygen graphviz python3-pip
sudo pip3 install sphinx sphinxcontrib-doxylink
-- On CentOS and Fedora::
+- On **CentOS** and **Fedora**:
+
+ .. code-block:: sh
sudo dnf config-manager --enable PowerTools # on CentOS only
sudo dnf install doxygen graphviz python3-pip
pip3 install --user sphinx sphinxcontrib-doxylink
-- On macOS::
+- On **macOS**:
+
+ .. code-block:: sh
brew install doxygen graphviz
sudo pip install sphinx sphinxcontrib-doxylink
-- On FreeBSD::
+- On **FreeBSD**:
+
+ .. code-block:: sh
sudo pkg install doxygen graphviz py37-sphinx
@@ -112,14 +120,18 @@
These are instructions for regular builds of ndn-cxx (release mode). If you are
planning to develop the ndn-cxx code itself, you should do a :ref:`Development build`.
-To build in a terminal, change directory to the ndn-cxx root, then enter::
+To build in a terminal, change directory to the ndn-cxx root, then enter:
+
+.. code-block:: sh
./waf configure # on CentOS, add --without-pch
./waf
sudo ./waf install
By default, only the shared variant of the ndn-cxx library will be built. To build the
-static library, pass ``--enable-static`` to the ``./waf configure`` command::
+static library, pass ``--enable-static`` to the ``./waf configure`` command:
+
+.. code-block:: sh
./waf configure --enable-static
@@ -127,12 +139,14 @@
additional ``--disable-shared`` option. Note that at least one variant of the library
needs to be enabled.
-::
+.. code-block:: sh
./waf configure --enable-static --disable-shared
On Linux, it is necessary to run the following command after the shared library has
-been installed::
+been installed:
+
+.. code-block:: sh
sudo ldconfig
@@ -142,12 +156,16 @@
additional actions may be necessary.
The installation path should be added to ``/etc/ld.so.conf`` (or in
- ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example::
+ ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example:
+
+ .. code-block:: sh
echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
- the installation directory of the shared library::
+ the installation directory of the shared library:
+
+ .. code-block:: sh
export LD_LIBRARY_PATH=/usr/local/lib
@@ -180,14 +198,18 @@
-------------------
By default, the examples in the ``examples/`` directory will not be built. To enable
-them, pass ``--with-examples`` during the configuration step::
+them, pass ``--with-examples`` during the configuration step:
+
+.. code-block:: sh
./waf configure --with-examples # on CentOS, add --without-pch
./waf
sudo ./waf install
sudo ldconfig # on Linux only
-To run the examples::
+To run the examples:
+
+.. code-block:: sh
# trivial producer app
./build/examples/producer
@@ -199,7 +221,9 @@
./build/examples/consumer-with-timer
If you want to make a new sample application, just create a ``.cpp`` file inside the
-``examples/`` directory and it will be compiled during the next run of ``./waf``::
+``examples/`` directory and it will be compiled during the next run of ``./waf``:
+
+.. code-block:: sh
cp examples/consumer.cpp examples/my-new-app.cpp
... # edit examples/my-new-app.cpp with your preferred editor
@@ -218,7 +242,7 @@
The following example shows how to completely disable debug symbols and configure
ndn-cxx to be installed into ``/usr`` with configuration in the ``/etc`` directory.
-::
+.. code-block:: sh
CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
./waf
@@ -229,14 +253,18 @@
To build ndn-cxx with a different compiler (rather than the platform default), set the
``CXX`` environment variable to point to the compiler binary. For example, to build
-with clang on Linux, use the following::
+with clang on Linux, use the following:
+
+.. code-block:: sh
CXX=clang++ ./waf configure
Building the documentation
--------------------------
-ndn-cxx tutorials and API documentation can be built using the following commands::
+ndn-cxx tutorials and API documentation can be built using the following commands:
+
+.. code-block:: sh
# Full set of documentation (tutorials + API) in build/docs
./waf docs
@@ -261,7 +289,9 @@
Development build
-----------------
-The following is the suggested build procedure for development builds::
+The following is the suggested build procedure for development builds:
+
+.. code-block:: sh
./waf configure --debug --with-tests # on CentOS, add --without-pch
./waf
@@ -270,7 +300,9 @@
In a development build, most compiler optimizations will be disabled and all warnings
will be treated as errors. This default behavior can be overridden by setting the
-``CXXFLAGS`` environment variable before running ``./waf configure``, for example::
+``CXXFLAGS`` environment variable before running ``./waf configure``, for example:
+
+.. code-block:: sh
CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
...
diff --git a/docs/code-style.rst b/docs/code-style.rst
index cc71192..bcc626b 100644
--- a/docs/code-style.rst
+++ b/docs/code-style.rst
@@ -7,7 +7,7 @@
The original document is available at `<http://geosoft.no/development/cppstyle.html>`_
* NDN Platform "C++, C, C#, Java and JavaScript Code Guidelines".
- The original document available at `<http://named-data.net/codebase/platform/documentation/ndn-platform-development-guidelines/cpp-code-guidelines/>`_
+ The original document available at `<https://named-data.net/codebase/platform/documentation/ndn-platform-development-guidelines/cpp-code-guidelines/>`_
1. Code layout
--------------
diff --git a/docs/conf.py b/docs/conf.py
index d3b203a..cd2092d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -23,10 +23,10 @@
copyright = u'Copyright © 2013-2020 Regents of the University of California.'
author = u'Named Data Networking Project'
-# The short X.Y version
+# The short X.Y version.
#version = ''
-# The full version, including alpha/beta/rc tags
+# The full version, including alpha/beta/rc tags.
#release = ''
# There are two options for replacing |today|: either, you set today to some
@@ -40,7 +40,7 @@
# If your documentation needs a minimal Sphinx version, state it here.
#
-needs_sphinx = '1.1'
+needs_sphinx = '1.3'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -87,6 +87,9 @@
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
+# Disable syntax highlighting of code blocks by default.
+highlight_language = 'none'
+
# -- Options for LaTeX output ------------------------------------------------
diff --git a/docs/examples.rst b/docs/examples.rst
index 33657da..0d89e20 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -5,7 +5,7 @@
To successfully run the following examples, please make sure that NFD is properly
configured and running. For more information about NFD, refer to `NFD's official
- homepage <http://named-data.net/doc/NFD/>`_.
+ homepage <https://named-data.net/doc/NFD/>`_.
Trivial consumer
----------------
diff --git a/docs/index.rst b/docs/index.rst
index dc3682b..ea459fb 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -40,13 +40,10 @@
releases
- :doc:`INSTALL`
-
- :doc:`examples`
-
- :doc:`tutorials`
- + `NDN Software Contributor's Guide <https://github.com/named-data/NFD/blob/master/CONTRIBUTING.md>`_ (guide for newcomers to the NDN community of software generally)
-
+ + `NDN Software Contributor's Guide <https://github.com/named-data/.github/blob/master/CONTRIBUTING.md>`_ (guide for newcomers to the NDN community of software generally)
+ :doc:`tutorials/utils-ndn-regex`
+ :doc:`tutorials/security-validator-config`
@@ -59,14 +56,12 @@
- :doc:`manpages`
-**Additional documentation**
+Additional Documentation
+^^^^^^^^^^^^^^^^^^^^^^^^
- `API documentation (doxygen) <doxygen/annotated.html>`_
-
- :doc:`code-style`
-
- :doc:`RELEASE_NOTES`
-
- :doc:`releases`
License
diff --git a/docs/manpages/ndn-client.conf.rst b/docs/manpages/ndn-client.conf.rst
index 5908972..a2bd6fc 100644
--- a/docs/manpages/ndn-client.conf.rst
+++ b/docs/manpages/ndn-client.conf.rst
@@ -6,13 +6,14 @@
The configuration file ``client.conf`` is looked up in several directories in the following order:
- ``$HOME/.ndn``: user-specific settings
-- ``@SYSCONFDIR@/ndn`` (``/usr/local/etc/ndn``, ``/opt/local/etc/ndn``, or other, depending how the
- library is configured): system-wide settings
+- ``SYSCONFDIR/ndn``: system-wide settings (where ``SYSCONFDIR`` can be ``/usr/local/etc``,
+ ``/opt/local/etc``, or other, depending on how the library is configured)
- ``/etc/ndn``: default system-wide settings
-Here is an example of ``client.conf`` for current ndn-cxx package:
+Here is an example of ``client.conf`` for the current ndn-cxx package:
.. literalinclude:: ../../client.conf.sample
+ :language: ini
NFD
diff --git a/docs/manpages/ndn-log.rst b/docs/manpages/ndn-log.rst
index 40db707..0a88f3e 100644
--- a/docs/manpages/ndn-log.rst
+++ b/docs/manpages/ndn-log.rst
@@ -46,11 +46,13 @@
Setting NDN_LOG requires the following syntax with as many prefixes and
corresponding loglevels as the user desires:
+.. code-block:: sh
+
export NDN_LOG="<prefix1>=<loglevel1>:<prefix2>=<loglevel2>"
-**Examples:**
+*Example:*
-::
+.. code-block:: sh
export NDN_LOG="ndn.*=DEBUG"
export NDN_LOG="ndn.UnixTransport=INFO"
@@ -59,30 +61,40 @@
**Note:**
-Shorter (general) prefixes should be placed before longer (specific) prefixes.
-Otherwise, the specific prefix's loglevel will be overwritten. For example,
-`export NDN_LOG="ndn.UnixTransport=TRACE:ndn.*=ERROR:*=INFO"` sets all modules
-to INFO; it should be written as
-`export NDN_LOG="*=INFO:ndn.*=ERROR:ndn.UnixTransport=TRACE"` for the desired effect.
+The loglevel assignments in ``NDN_LOG`` are processed left-to-right. Thus, shorter
+(more general) prefixes should be listed before longer (more specific) prefixes.
+Otherwise, the loglevel setting of a more specific prefix may be overwritten by a
+more general assignment appearing later in the string. For example:
+
+.. code-block:: sh
+
+ export NDN_LOG="ndn.UnixTransport=TRACE:ndn.*=ERROR:*=INFO"
+
+will set all modules to INFO. To obtain the desired effect, it should instead be
+written as:
+
+.. code-block:: sh
+
+ export NDN_LOG="*=INFO:ndn.*=ERROR:ndn.UnixTransport=TRACE"
**Note:**
Setting the environment variable with sudo requires the application to be run
in the same command.
-::
+.. code-block:: sh
- Correct:
+ # Correct
+ sudo env NDN_LOG=logLevel ./ndn-application
- sudo env NDN_LOG=logLevel ./ndn-application
+ # Also correct
+ sudo -s
+ export NDN_LOG=logLevel
+ ./ndn-application
- sudo -s
- export NDN_LOG=logLevel
- ./ndn-application
+ # Incorrect
+ sudo export NDN_LOG=logLevel
+ sudo ./ndn-application
- Incorrect:
-
- sudo export NDN_LOG=logLevel
- sudo ./ndn-application
-
- NDN_LOG=logLevel sudo ./ndn-application
+ # Incorrect
+ NDN_LOG=logLevel sudo ./ndn-application
diff --git a/docs/release-notes/release-notes-0.1.0.rst b/docs/release-notes/release-notes-0.1.0.rst
index a8cf1bc..0e0ac7f 100644
--- a/docs/release-notes/release-notes-0.1.0.rst
+++ b/docs/release-notes/release-notes-0.1.0.rst
@@ -17,17 +17,17 @@
- **Base**
+ Fully asynchronous, event-driven communication model, which is implemented using `Boost.Asio
- <http://www.boost.org/doc/libs/1_48_0/doc/html/boost_asio.html>`_
+ <https://www.boost.org/doc/libs/1_48_0/doc/html/boost_asio.html>`_
+ Single-threaded, but thread-safe Face operations
A single Face object can be safely used in multiple threads to express Interests and
publish Data packets
+ Explicit time management for NDN operations using `Boost.Chrono
- <http://www.boost.org/doc/libs/1_48_0/doc/html/chrono.html>`_
+ <https://www.boost.org/doc/libs/1_48_0/doc/html/chrono.html>`_
+ Simplified and extended `NDN API <doxygen/annotated.html>`_
+ Extensive set of unit-tests based on `Boost.Test framework
- <http://www.boost.org/doc/libs/1_48_0/libs/test/doc/html/index.html>`_
+ <https://www.boost.org/doc/libs/1_48_0/libs/test/doc/html/index.html>`_
- Continuous integration using an in-house installation of Jenkins build bots and the
hosted `Travis CI <https://travis-ci.org/named-data/ndn-cxx>`_ continuous
@@ -35,7 +35,7 @@
- **Wire format**
- + Full support of `NDN-TLV packet format v0.1 <http://named-data.net/doc/NDN-TLV/0.1/>`_
+ + Full support of `NDN-TLV packet format v0.1 <https://named-data.net/doc/NDN-packet-spec/0.1/>`_
+ Pure C++ implementation of wire encoding/decoding with simple access to wire format
of all NDN packet abstractions via ``wireEncode`` and ``wireDecode`` methods
diff --git a/docs/release-notes/release-notes-0.2.0.rst b/docs/release-notes/release-notes-0.2.0.rst
index 26ab722..8529024 100644
--- a/docs/release-notes/release-notes-0.2.0.rst
+++ b/docs/release-notes/release-notes-0.2.0.rst
@@ -5,8 +5,8 @@
Changes since version 0.1.0:
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
- **Base**
@@ -22,8 +22,9 @@
allow distinct operations of registering with the local NDN forwarder and setting
up application-specific ``OnInterest`` call dispatch using InterestFilters.
- + Add support for new `NDN naming conventions
- <http://named-data.net/doc/tech-memos/naming-conventions.pdf>`_ (:issue:`1761`)
+ + Add support for the `NDN naming conventions (revision 1)
+ <https://named-data.net/publications/techreports/ndn-tr-22-ndn-memo-naming-conventions/>`_
+ (:issue:`1761`)
- **Security**
@@ -37,7 +38,7 @@
+ New :ndn-cxx:`SignatureSha256WithEcdsa` signature type
+ Updates in :ndn-cxx:`Signature` data structure to reflect changes in `NDN-TLV spec
- 0.1.1 <http://named-data.net/doc/NDN-TLV/0.1.1/>`_
+ 0.1.1 <https://named-data.net/doc/NDN-packet-spec/0.1.1/>`_
- **Wire encoding**
@@ -72,8 +73,8 @@
+ Enabled support of precompiled headers for clang and gcc compilers to speed up compilation
-Updates and bug fixes:
-^^^^^^^^^^^^^^^^^^^^^^
+Updates and bug fixes
+^^^^^^^^^^^^^^^^^^^^^
- **Base**
@@ -111,7 +112,7 @@
``ndnsec-certgen``
+ ``SignatureSha256`` has been renamed to :ndn-cxx:`DigestSha256` to conform to
- `NDN-TLV specification <http://named-data.net/doc/ndn-tlv/>`_
+ `NDN-TLV specification <https://named-data.net/doc/NDN-packet-spec/0.1.1/>`_
+ Add checking of Timestamp and Nonce fields in signed Interest within
:ndn-cxx:`ValidatorConfig`
@@ -135,8 +136,8 @@
- Other minor fixes and corrections
-Deprecated:
-^^^^^^^^^^^
+Deprecated
+^^^^^^^^^^
- ``SignatureSha256`` class, use :ndn-cxx:`DigestSha256` instead.
@@ -160,8 +161,8 @@
- ``CommandInterestGenerator`` and ``CommandInterestValidator`` utility classes.
:ndn-cxx:`ValidatorConfig` should be used instead.
-Removed:
-^^^^^^^^
+Removed
+^^^^^^^
- Support for ndnd-tlv (only NFD management protocol is supported now)
diff --git a/docs/release-notes/release-notes-0.3.0.rst b/docs/release-notes/release-notes-0.3.0.rst
index c51d682..8c2efe1 100644
--- a/docs/release-notes/release-notes-0.3.0.rst
+++ b/docs/release-notes/release-notes-0.3.0.rst
@@ -5,8 +5,8 @@
Changes since version 0.2.0:
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
- **Build**
@@ -85,8 +85,8 @@
+ New NetworkMonitor helper to detect network state changes (:issue:`2443`)
-Updates and bug fixes:
-^^^^^^^^^^^^^^^^^^^^^^
+Updates and bug fixes
+^^^^^^^^^^^^^^^^^^^^^
- **Base**
@@ -198,8 +198,8 @@
- Other minor fixes and corrections
-Deprecated:
-^^^^^^^^^^^
+Deprecated
+^^^^^^^^^^
- ``ndn::ptr_lib`` and ``ndn::func_lib`` namespace aliases
@@ -216,8 +216,8 @@
- ``EventEmitter`` is deprecated in favor of ``Signal``
-Removed:
-^^^^^^^^
+Removed
+^^^^^^^
- FaceFlags APIs (:issue:`1992`)
diff --git a/docs/release-notes/release-notes-0.3.1.rst b/docs/release-notes/release-notes-0.3.1.rst
index 7f8a9f0..e48b00d 100644
--- a/docs/release-notes/release-notes-0.3.1.rst
+++ b/docs/release-notes/release-notes-0.3.1.rst
@@ -5,8 +5,8 @@
Changes since version 0.3.0:
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
- **Management**
@@ -17,8 +17,8 @@
- Add CachingPolicy to ``LocalControlHeader`` (:issue:`2183`)
-Updates and bug fixes:
-^^^^^^^^^^^^^^^^^^^^^^
+Updates and bug fixes
+^^^^^^^^^^^^^^^^^^^^^
- **Wire encoding**
@@ -51,8 +51,8 @@
- Explicitly define ``_GLIBCXX_USE_NANOSLEEP``, necessary for gcc < 4.8 in some environments
(:issue:`2499`)
-Removed:
-^^^^^^^^
+Removed
+^^^^^^^
- Delete deprecated ``Block(std::istream&)`` constructor (:issue:`2241`)
diff --git a/docs/release-notes/release-notes-0.3.2.rst b/docs/release-notes/release-notes-0.3.2.rst
index 90abf8e..ca2456b 100644
--- a/docs/release-notes/release-notes-0.3.2.rst
+++ b/docs/release-notes/release-notes-0.3.2.rst
@@ -5,8 +5,8 @@
Changes since version 0.3.1:
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
- Add Link abstraction (:issue:`2587`)
@@ -18,8 +18,8 @@
* In-memory PIB implementation
* Define new abstraction for identity, key, and certificate
-Updates and bug fixes:
-^^^^^^^^^^^^^^^^^^^^^^
+Updates and bug fixes
+^^^^^^^^^^^^^^^^^^^^^
- Enable decoding Exclude containing ImplicitSha256DigestComponent (:issue:`2629`)
@@ -35,13 +35,13 @@
- Disable precompiled headers on OS X with clang < 6.1.0 (:issue:`2804`)
-Deprecated:
-^^^^^^^^^^^
+Deprecated
+^^^^^^^^^^
- `Block::fromBuffer` overloads with output parameter (:issue:`2553`)
-Removed:
-^^^^^^^^
+Removed
+^^^^^^^
- Delete deprecated Controller functions:
diff --git a/docs/release-notes/release-notes-0.3.3.rst b/docs/release-notes/release-notes-0.3.3.rst
index d7aeecf..d26da2b 100644
--- a/docs/release-notes/release-notes-0.3.3.rst
+++ b/docs/release-notes/release-notes-0.3.3.rst
@@ -5,8 +5,8 @@
Changes since version 0.3.2:
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
- Allow compilation of ndn-cxx as a shared library (:issue:`2243`)
@@ -41,8 +41,8 @@
* ``makeStringBlock``
* ``readString``
-Improvements and bug fixes:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Improvements and bug fixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
- Use C++11 lambda expression and smart pointers in Face implementation (:issue:`2112`)
@@ -72,8 +72,8 @@
restrictive move operation (`move_if_noexcept`) is used (e.g., in STL library's containers)
(:issue:`2966`)
-Deprecated:
-^^^^^^^^^^^
+Deprecated
+^^^^^^^^^^
- The following ``KeyChain::sign*`` methods, in favor of generalized ``KeyChain::sign(..., SigningInfo)``
@@ -101,21 +101,21 @@
* ``CommandOptions::setSigningIdentity``
* ``CommandOptions::setSigningCertificate``
-Removed:
-^^^^^^^^
+Removed
+^^^^^^^
- Remove SCOPE from Interests and all references to it in the related code (:issue:`2345`)
-- Direct FIB management in Face class (:issue:`2533`)
+- Direct FIB management in Face class (:issue:`2533`).
``Face::register`` and ``Face::setInterestFilter`` methods now only support NFD RIB management
protocol.
For special needs, FIB management can be implemented using ``nfd::Controller``
- (``start<FibAddNextHopCommand>``, and ``start<FibRemoveNextHopCommand>``)
+ (``start<FibAddNextHopCommand>`` and ``start<FibRemoveNextHopCommand>``).
-Upcoming features (partially finished in development branches):
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Upcoming features (partially finished in development branches)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- NDNLPv2 (https://redmine.named-data.net/projects/nfd/wiki/NDNLPv2, :issue:`2520`,
:issue:`2879`, :issue:`2763`, :issue:`2883`, :issue:`2841`, :issue:`2866`)
diff --git a/docs/release-notes/release-notes-0.3.4.rst b/docs/release-notes/release-notes-0.3.4.rst
index ec6703b..64098b1 100644
--- a/docs/release-notes/release-notes-0.3.4.rst
+++ b/docs/release-notes/release-notes-0.3.4.rst
@@ -5,8 +5,8 @@
Changes since version 0.3.3:
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
- By default, library is now compiled as a shared library (:issue:`2867`)
@@ -26,8 +26,8 @@
- New Dispatcher class to simplify server-side implementation of NFD management protocol
(:issue:`2107`)
-Improvements and bug fixes:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Improvements and bug fixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
- Fix compilation error with Boost 1.59 (:issue:`3128`)
@@ -44,8 +44,8 @@
- Add ability to create ``util::Digest`` object from ``std::istream&`` (:issue:`3022`)
-Deprecated:
-^^^^^^^^^^^
+Deprecated
+^^^^^^^^^^
- The following methods of ``CommandOptions`` class in favor of ``getSigningInfo`` and
``setSigningInfo`` methods (:issue:`2893`):
@@ -61,8 +61,8 @@
- Overloads of ``Face::registerPrefix`` and ``Face::setInterestFilter`` that do not accept
SigningInfo parameter (:issue:`2932`)
-Upcoming features (partially implemented in development branches):
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Upcoming features (partially implemented in development branches)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Introduce new API to simplify security transformations (:issue:`3009`)
diff --git a/docs/release-notes/release-notes-0.4.0.rst b/docs/release-notes/release-notes-0.4.0.rst
index c32846c..a7900bc 100644
--- a/docs/release-notes/release-notes-0.4.0.rst
+++ b/docs/release-notes/release-notes-0.4.0.rst
@@ -8,8 +8,8 @@
Changes since version 0.3.4:
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
- **(breaking change)** LocalControlHeader for special signaling between application and NFD has
been replaced with NDNLPv2 signaling (:issue:`2879`, :issue:`2930`)
@@ -32,8 +32,8 @@
- Ability to create Face with custom IO service and default transport (:issue:`2500`)
-Improvements and bug fixes:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Improvements and bug fixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
- **(breaking change)** SegmentFetcher helper changed to use asynchronous data validation (:issue:`2734`)
@@ -46,8 +46,8 @@
- Minor documentation updates (:issue:`3207`, :issue:`3210`, :issue:`3221`)
-Deprecated:
-^^^^^^^^^^^
+Deprecated
+^^^^^^^^^^
- Overloads of ``Face::registerPrefix`` and ``Face::setInterestFilter`` that do not accept
SigningInfo parameter (:issue:`2932`)
@@ -61,13 +61,13 @@
- ndn::util::DummyClientFace::sentDatas, use ndn::util::DummyClientFace.sentData instead
(:issue:`3146`)
-Removed:
-^^^^^^^^
+Removed
+^^^^^^^
- Deprecated EventEmitter class (:issue:`2351`)
-Planned features for future releases:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Planned features for future releases
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Introduce new API to simplify security transformations (:issue:`3009`)
diff --git a/docs/release-notes/release-notes-0.4.1.rst b/docs/release-notes/release-notes-0.4.1.rst
index f3001d1..c22f2d5 100644
--- a/docs/release-notes/release-notes-0.4.1.rst
+++ b/docs/release-notes/release-notes-0.4.1.rst
@@ -5,8 +5,8 @@
Changes since version 0.4.0:
-Improvements and bug fixes:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Improvements and bug fixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
- Improved support for ECDSA signatures (:issue:`3438`, :issue:`3439`)
@@ -15,14 +15,14 @@
- Use InMemoryStorage for StatusDataset and Notification produced by managers based on
Dispatcher class (:issue:`2182`)
-Removed:
-^^^^^^^^
+Removed
+^^^^^^^
- Deprecated ``tlvdump`` command-line tool (use ``ndn-dissect`` tool from `NDN Essential Tools
<https://github.com/named-data/ndn-tools>`__ instead
-Planned features for future releases:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Planned features for future releases
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Introduce new API to simplify security transformations (:issue:`3009`)
diff --git a/docs/release-notes/release-notes-0.5.0.rst b/docs/release-notes/release-notes-0.5.0.rst
index 199840c..b81f209 100644
--- a/docs/release-notes/release-notes-0.5.0.rst
+++ b/docs/release-notes/release-notes-0.5.0.rst
@@ -15,8 +15,8 @@
Changes since version 0.4.1:
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
- New transformation API (:issue:`3009`)
@@ -104,7 +104,7 @@
- ``ndn::crypto::sha256`` in favor of ``ndn::crypto::computeSha256Digest``
- ``security/cryptopp.hpp`` header. Use ``security/v1/cryptopp.hpp`` when needed, avoid direct
- include as CryptoPP dependency may be removed from future versions of the library.
+ include as CryptoPP dependency will be removed from future versions of the library.
- ``security/identity-certificate.hpp`` header. Use ``security/v1/identity-certificate.hpp`` instead.
diff --git a/docs/release-notes/release-notes-0.5.1.rst b/docs/release-notes/release-notes-0.5.1.rst
index cdb555a..8e1acc9 100644
--- a/docs/release-notes/release-notes-0.5.1.rst
+++ b/docs/release-notes/release-notes-0.5.1.rst
@@ -10,8 +10,8 @@
Changes since version 0.5.0:
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
- Add version 2 of the security framework (introduced in ``security::v2`` namespace)
diff --git a/docs/release-notes/release-notes-0.6.0.rst b/docs/release-notes/release-notes-0.6.0.rst
index f774775..4beb3ef 100644
--- a/docs/release-notes/release-notes-0.6.0.rst
+++ b/docs/release-notes/release-notes-0.6.0.rst
@@ -5,18 +5,18 @@
Changes since version 0.5.1:
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
-- **breaking change** Security framework version 2 (:issue:`3098`, :issue:`3920`,
- :issue:`3644`, :issue:`4085`, :issue:`4323`, :issue:`4339`)
+- **(breaking change)** Security framework version 2 (:issue:`3098`, :issue:`3920`,
+ :issue:`3644`, :issue:`4085`, :issue:`4323`, :issue:`4339`).
- The released version of the library only supports the new version of the security (v2
- certificate format) and features a number of updates of KeyChain and Validator
- interfaces. At the same time, management APIs for :ndn-cxx:`ValidatorConfig` remained
- intact; transition to the new framework would require only adjusting
- :ndn-cxx:`Validator::validate` calls and updating configuration files to follow the new
- naming conventions of :ref:`NDN Certificate Format Version 2.0`.
+ The released version of the library only supports the new version of the security (v2
+ certificate format) and features a number of updates of KeyChain and Validator
+ interfaces. At the same time, management APIs for :ndn-cxx:`ValidatorConfig` remained
+ intact; transition to the new framework would require only adjusting
+ :ndn-cxx:`Validator::validate` calls and updating configuration files to follow the new
+ naming conventions of :ref:`NDN Certificate Format Version 2.0`.
- Integration of fetching certificates using Certificate Bundle as part of specialized
``CertificateFetcher`` (:issue:`3891`)
diff --git a/docs/release-notes/release-notes-0.6.1.rst b/docs/release-notes/release-notes-0.6.1.rst
index c1f5a4f..95a7dbb 100644
--- a/docs/release-notes/release-notes-0.6.1.rst
+++ b/docs/release-notes/release-notes-0.6.1.rst
@@ -3,8 +3,8 @@
Release date: February 19, 2018
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
- (potentially breaking change) :ndn-cxx:`expressInterest` now by default loopbacks Interests to
producer callbacks on the same :ndn-cxx:`Face`. When undesired, use
diff --git a/docs/release-notes/release-notes-0.6.2.rst b/docs/release-notes/release-notes-0.6.2.rst
index 3c48aeb..9864fd2 100644
--- a/docs/release-notes/release-notes-0.6.2.rst
+++ b/docs/release-notes/release-notes-0.6.2.rst
@@ -3,11 +3,11 @@
Release date: May 4, 2018
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
-- Initial support for [NDN packet format version
- 0.3](https://named-data.net/doc/NDN-packet-spec/0.3/) (:issue:`4527`)
+- Initial support for `NDN packet format version 0.3
+ <https://named-data.net/doc/NDN-packet-spec/0.3/>`__ (:issue:`4527`)
* Recognize typed name components, allow typed name component in ``FinalBlockId``
(:issue:`4526`)
@@ -41,7 +41,7 @@
- Logging system improvements (:issue:`4552`)
Deprecated
-~~~~~~~~~~
+^^^^^^^^^^
- Selectors (:issue:`4527`)
diff --git a/docs/release-notes/release-notes-0.6.3.rst b/docs/release-notes/release-notes-0.6.3.rst
index 863e246..7f8769d 100644
--- a/docs/release-notes/release-notes-0.6.3.rst
+++ b/docs/release-notes/release-notes-0.6.3.rst
@@ -9,11 +9,11 @@
The compilation now uses the C++14 standard.
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
-- More support for `NDN packet format version
- 0.3 <https://named-data.net/doc/NDN-packet-spec/0.3/>`__ (:issue:`4527`)
+- More support for `NDN packet format version 0.3
+ <https://named-data.net/doc/NDN-packet-spec/0.3/>`__ (:issue:`4527`)
- Allow applications to declare a default ``CanBePrefix`` setting (:issue:`4581`)
@@ -67,7 +67,7 @@
- Correct and improve documentation
Deprecated
-~~~~~~~~~~
+^^^^^^^^^^
- ``SegmentFetcher::fetch()`` static functions in favor of ``start()`` (:issue:`4464`)
@@ -83,6 +83,6 @@
- ``Data::get/setFinalBlockId()`` in favor of ``Data::get/setFinalBlock()``
Removed
-~~~~~~~
+^^^^^^^
- Dependency on Boost.Regex in favor of ``std::regex``
diff --git a/docs/release-notes/release-notes-0.6.5.rst b/docs/release-notes/release-notes-0.6.5.rst
index a9e6ac7..62af06d 100644
--- a/docs/release-notes/release-notes-0.6.5.rst
+++ b/docs/release-notes/release-notes-0.6.5.rst
@@ -3,8 +3,8 @@
Release date: February 4, 2019
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
- More support for `NDN packet format version
0.3 <https://named-data.net/doc/NDN-packet-spec/0.3/>`__ (:issue:`4527`)
@@ -58,7 +58,7 @@
- Reimplement ``scheduler::EventId`` with ``CancelHandle`` (:issue:`4698`)
Deprecated
-~~~~~~~~~~
+^^^^^^^^^^
- ``ndn-cxx/util/scheduler-scoped-event-id.hpp`` header as it is now sufficient to use
``ndn-cxx/util/scheduler.hpp`` header (:issue:`4698`)
@@ -66,7 +66,7 @@
- Implicit conversion from nullptr to ``scheduler::EventId`` (:issue:`4698`)
Removed
-~~~~~~~
+^^^^^^^
- ``ndn::ip::address{,V6}FromString``
diff --git a/docs/release-notes/release-notes-0.6.6.rst b/docs/release-notes/release-notes-0.6.6.rst
index a69cd8b..e09f916 100644
--- a/docs/release-notes/release-notes-0.6.6.rst
+++ b/docs/release-notes/release-notes-0.6.6.rst
@@ -3,16 +3,17 @@
Release date: April 27, 2019
-Note that this is the last release that encodes to `NDN packet format version 0.2.1
-<https://named-data.net/doc/NDN-packet-spec/0.2.1/>`__. A future release will continue to
-decode v0.2.1 format, but will encode to `v0.3 format
-<https://named-data.net/doc/NDN-packet-spec/0.3/>`__.
+.. note::
+ This is the last release to support the `NDN packet format version 0.2.1
+ <https://named-data.net/doc/NDN-packet-spec/0.2.1/>`__.
+ The next release will be able to encode and decode only the `v0.3 packet format
+ <https://named-data.net/doc/NDN-packet-spec/0.3/>`__.
-New features:
-^^^^^^^^^^^^^
+New features
+^^^^^^^^^^^^
-- More support for `NDN packet format version
- 0.3 <https://named-data.net/doc/NDN-packet-spec/0.3/>`__ (:issue:`4527`)
+- More support for `NDN packet format version 0.3
+ <https://named-data.net/doc/NDN-packet-spec/0.3/>`__ (:issue:`4527`)
* Support new naming conventions to encode/decode segment numbers, byte offsets, versions,
timestamps, and sequence numbers based on typed name components (:issue:`4777`)
@@ -34,7 +35,8 @@
``ApplicationParameters`` and to change its number to be a non-critical element type
(:issue:`4658`, :issue:`4780`)
-- Add option to disable infrastructure interest in ``CertificateFetcherDirectFetch`` (:issue:`4879`)
+- Add an option to disable the infrastructure Interest in ``CertificateFetcherDirectFetch``
+ (:issue:`4879`)
- Fix compilation against recent versions of Boost libraries and issues with Xcode 10.2 and
older versions of Boost libraries (:issue:`4890`, :issue:`4923`, :issue:`4860`)
@@ -44,7 +46,7 @@
- Improve documentation
Deprecated
-~~~~~~~~~~
+^^^^^^^^^^
- ``PendingInterestId``, ``RegisteredPrefixId``, and ``InterestFilterId`` types in favor of
``PendingInterestHandle``, ``RegisteredPrefixHandle``, and ``InterestFilterHandle``
diff --git a/docs/release-notes/release-notes-0.7.0.rst b/docs/release-notes/release-notes-0.7.0.rst
index 2b137c9..523a58d 100644
--- a/docs/release-notes/release-notes-0.7.0.rst
+++ b/docs/release-notes/release-notes-0.7.0.rst
@@ -8,9 +8,9 @@
This release features support of only `NDN packet format version 0.3
<https://named-data.net/doc/NDN-packet-spec/0.3/>`__ (:issue:`4527`, :issue:`4567`,
:issue:`4709`, :issue:`4913`). The library encodes and interprets Interest and Data
-packets only in 0.3 format; support for version 0.2 has been completely removed. In
-addition, the URI representation of Interest packets has also been changed following the
-packet format updates.
+packets only in 0.3 format; support for version 0.2 has been completely removed. In
+addition, the URI representation of Interest packets has been updated to follow the
+packet format changes.
New features
^^^^^^^^^^^^
diff --git a/docs/specs/certificate-format.rst b/docs/specs/certificate-format.rst
index f1ec424..9e811b9 100644
--- a/docs/specs/certificate-format.rst
+++ b/docs/specs/certificate-format.rst
@@ -3,8 +3,6 @@
NDN Certificate Format Version 2.0
==================================
-.. contents::
-
Since signature verification is a common operation in NDN applications, it is
important to define a common certificate format to standardize the public key
authentication procedure. As every NDN data packet is signed, a data packet
@@ -46,27 +44,26 @@
| SignatureValue |
+--------------------------+
+.. code-block:: abnf
- CertificateV2 = DATA-TYPE TLV-LENGTH
- Name ; /<NameSpace>/KEY/[KeyId]/[IssuerId]/[Version]
- MetaInfo ; ContentType = KEY, FreshnessPeriod required
- Content ; X509PublicKey
- CertificateV2SignatureInfo
- SignatureValue
+ CertificateV2 = DATA-TYPE TLV-LENGTH
+ Name ; /<NameSpace>/KEY/[KeyId]/[IssuerId]/[Version]
+ MetaInfo ; ContentType == KEY, FreshnessPeriod required
+ Content ; X509PublicKey
+ CertificateV2SignatureInfo
+ SignatureValue
- CertificateV2SignatureInfo = SIGNATURE-INFO-TYPE TLV-LENGTH
- SignatureType
- KeyLocator
- ValidityPeriod
- *CertificateV2Extension
+ CertificateV2SignatureInfo = SIGNATURE-INFO-TYPE TLV-LENGTH
+ SignatureType
+ KeyLocator
+ ValidityPeriod
+ *CertificateV2Extension
Name
----
-The name of a certificate consists of five parts as shown below:
-
-::
+The name of a certificate consists of five parts as shown below::
/<SubjectName>/KEY/[KeyId]/[IssuerId]/[Version]
@@ -82,17 +79,13 @@
controlled by the certificate issuer and, similar to KeyId, can be an 8-byte random number,
SHA-256 digest of the issuer's public key, or a simple numerical identifier.
-
-For example,
-
-::
+For example::
/edu/ucla/cs/yingdi/KEY/%03%CD...%F1/%9F%D3...%B7/%FD%d2...%8E
\_________________/ \___________/ \___________/\___________/
Certificate Namespace Key Id Issuer Id Version
(Identity)
-
MetaInfo
--------
@@ -120,7 +113,7 @@
Using ISO style string is the convention of specifying the validity period of certificate,
which has been adopted by many certificate systems, such as X.509, PGP, and DNSSEC.
-::
+.. code-block:: abnf
ValidityPeriod = VALIDITY-PERIOD-TYPE TLV-LENGTH
NotBefore
@@ -180,7 +173,7 @@
``("Organization", "UCLA")``. The issuer of a certificate can specify arbitrary
key-value pair to provide additional description about the certificate.
-::
+.. code-block:: abnf
CertificateV2Extension = AdditionalDescription
diff --git a/docs/specs/safe-bag.rst b/docs/specs/safe-bag.rst
index fcb6211..23e93cb 100644
--- a/docs/specs/safe-bag.rst
+++ b/docs/specs/safe-bag.rst
@@ -1,24 +1,24 @@
-Export/Import Credentials
-=========================
+SafeBag Format for Exported Credentials
+=======================================
Sometimes, one may need to export credentials (e.g., certificate and private key) from
one machine, and import them into another machine. This requires a secured container for
sensitive information. We define **SafeBag**, which contains both an NDN certificate
(:doc:`version 2.0 <certificate-format>`) and the corresponding private
-key which is encrypted in `PKCS#8 format <https://tools.ietf.org/html/rfc5208>`_.
+key, which is encrypted in `PKCS #8 format <https://tools.ietf.org/html/rfc5208>`_.
The format of **SafeBag** is defined as:
-::
+.. code-block:: abnf
SafeBag = SAFE-BAG-TYPE TLV-LENGTH
- CertificateV2 ; a data packet following certificate format spec
+ CertificateV2
EncryptedKeyBag
EncryptedKeyBag = ENCRYPTED-KEY-BAG-TYPE TLV-LENGTH
- *OCTET ; private key encrypted in PKCS#8 format
+ *OCTET ; private key encrypted in PKCS #8 format
-All TLV-TYPE codes are application specific:
+All TLV-TYPE numbers are application specific:
+---------------------------------------------+-------------------+----------------+
| TLV-TYPE | Assigned number | Assigned number|
diff --git a/docs/specs/signed-interest.rst b/docs/specs/signed-interest.rst
index f283b7f..b854c13 100644
--- a/docs/specs/signed-interest.rst
+++ b/docs/specs/signed-interest.rst
@@ -18,7 +18,7 @@
+-------------+----------+-----------------------------------------------------------------------------------+
| Interest | Interest | +------+--------+--------------------------------------------------+ +----------+ |
- | Type (0x01) | length | | Name | Name | +---------+-- --+---------+---------+---------+| | Other | |
+ | Type (0x05) | length | | Name | Name | +---------+-- --+---------+---------+---------+| | Other | |
| | | | Type | Length | |Component| ... |Component|Component|Component|| | TLVs ... | |
| | | | | | | TLV 1 | | TLV n-2 | TLV n-1 | TLV n || | in | |
| | | | | | +---------+-- --+---------+---------+---------+| | Interest | |
@@ -32,14 +32,12 @@
More specifically, the SignedInterest is defined to have four additional components:
-- ``<timestamp>``
-- ``<nonce>``
-- ``<SignatureInfo>``
-- ``<SignatureValue>``
+- ``timestamp``
+- ``nonce``
+- ``SignatureInfo``
+- ``SignatureValue``
-For example, for ``/signed/interest/name`` name, CommandInterest will be defined as:
-
-::
+For example, for ``/signed/interest/name`` name, CommandInterest will be defined as::
/signed/interest/name/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>
diff --git a/docs/tutorials/security-validator-config.rst b/docs/tutorials/security-validator-config.rst
index fcd49dc..69edc45 100644
--- a/docs/tutorials/security-validator-config.rst
+++ b/docs/tutorials/security-validator-config.rst
@@ -51,8 +51,7 @@
file-name "testbed-trust-anchor.cert"
}
-.. note::
- **ATTENTION: The order of rules MATTERS!**
+.. attention:: **The order of rules MATTERS!**
A rule can be broken into two parts:
@@ -97,8 +96,7 @@
packets passed to it. A rule may contain multiple filters, in this case, a packet
is captured by the rule only if all filters are satisfied.
-.. note::
- **ATTENTION: A packet that satisfies all the filters may not be valid**.
+.. attention:: **A packet that satisfies all the filters may not be valid.**
The **checker** property defines the conditions that a matched packet must fulfill to be
treated as a valid packet. A rule must have at least one **checker** property. A packet is
@@ -377,9 +375,9 @@
There is also a special trust anchor **any**. As long as such a trust-anchor is defined
in config file, packet validation will be turned off.
-.. note::
- **ATTENTION: This type of trust anchor is dangerous. You should used it only when you
- want to disable packet validation temporarily (e.g, debugging code, building a demo).**
+.. danger::
+ This type of trust anchor is dangerous. You should used it only when you
+ want to disable packet validation temporarily (e.g., debugging code, building a demo).
::