docs: fix/improve the structure of several documents
Change-Id: Ib8acd4bf29baf19b78d25cabc1a873eeeec15da6
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index 82fa64b..755da6f 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -41,39 +41,34 @@
To build ndn-cxx from source, one must first install a C++ compiler and all necessary
development tools and libraries:
-- On **Debian** and **Ubuntu**
+- On **Debian** and **Ubuntu**, run in a terminal:
- In a terminal, enter::
+ .. code-block:: shell
- sudo apt install build-essential libboost-all-dev libssl-dev libsqlite3-dev pkgconf python3
+ sudo apt install build-essential libboost-all-dev libssl-dev libsqlite3-dev pkgconf python3
-- On **CentOS** and **Fedora**
+- On **CentOS** and **Fedora**, run in a terminal:
- In a terminal, enter::
+ .. code-block:: shell
- sudo dnf install gcc-c++ boost-devel openssl-devel sqlite-devel pkgconf python3
+ sudo dnf install gcc-c++ boost-devel openssl-devel sqlite-devel pkgconf python3
- On **macOS**
- * Install either Xcode (from the App Store) or the Command Line Tools
- (with ``xcode-select --install``)
+ * Install either Xcode (from the App Store) or the Command Line Tools
+ (with ``xcode-select --install``)
- * If using Homebrew (recommended), enter the following in a terminal:
+ * If using Homebrew (recommended), enter the following in a terminal:
- .. code-block:: sh
+ .. code-block:: shell
- brew install boost openssl pkgconf
+ brew install boost openssl pkgconf
- .. warning::
+- On **FreeBSD**, run in a terminal:
- If a major OS upgrade is performed after installing the dependencies
- with Homebrew, remember to reinstall all packages.
+ .. code-block:: shell
-- On **FreeBSD**
-
- In a terminal, enter::
-
- sudo pkg install boost-libs openssl sqlite3 pkgconf python3
+ sudo pkg install boost-libs openssl sqlite3 pkgconf python3
Optional
~~~~~~~~
@@ -83,56 +78,57 @@
- doxygen
- graphviz
-- sphinx
-- sphinxcontrib-doxylink
+- `sphinx <https://www.sphinx-doc.org/>`__
+- `sphinxcontrib-doxylink <https://github.com/sphinx-contrib/doxylink>`__
+- `furo <https://pradyunsg.me/furo/>`__
The following lists the steps to install these prerequisites on various common platforms.
-.. note::
+.. tip::
On Linux, you may need to add ``$HOME/.local/bin`` to the ``PATH`` environment variable
for your user, for example:
- .. code-block:: sh
+ .. code-block:: shell
- export PATH="${HOME}/.local/bin${PATH:+:}${PATH}"
+ export PATH="${HOME}/.local/bin${PATH:+:}${PATH}"
- On **Debian** and **Ubuntu**:
- .. code-block:: sh
+ .. code-block:: shell
sudo apt install doxygen graphviz python3-pip
python3 -m pip install --user -r docs/requirements.txt
- On **CentOS** and **Fedora**:
- .. code-block:: sh
+ .. code-block:: shell
sudo dnf install doxygen graphviz python3-pip
python3 -m pip install --user -r docs/requirements.txt
- On **macOS**:
- .. code-block:: sh
+ .. code-block:: shell
brew install doxygen graphviz
python3 -m pip install --user -r docs/requirements.txt
- On **FreeBSD**:
- .. code-block:: sh
+ .. code-block:: shell
sudo pkg install doxygen graphviz py39-sphinx
-Build
------
+Building
+--------
.. note::
- 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`.
+ These are the instructions for a regular build of ndn-cxx (release mode). If you are planning
+ to develop or modify 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:
-.. code-block:: sh
+.. code-block:: shell
./waf configure
./waf
@@ -141,7 +137,7 @@
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:
-.. code-block:: sh
+.. code-block:: shell
./waf configure --enable-static
@@ -149,25 +145,25 @@
additional ``--disable-shared`` option. Note that at least one variant of the library
needs to be enabled.
-.. code-block:: sh
+.. code-block:: shell
./waf configure --enable-static --disable-shared
On Linux, it is necessary to run the following command after the shared library has
been installed:
-.. code-block:: sh
+.. code-block:: shell
sudo ldconfig
-.. note::
+.. tip::
On Linux, when the library is installed in a non-default location (generally, not in
``/usr/lib`` or ``/usr/local/lib``), the following additional actions may be necessary.
The library installation path should be added to ``/etc/ld.so.conf`` or to
``/etc/ld.so.conf.d/*.conf`` before running ``ldconfig``. For example:
- .. code-block:: sh
+ .. code-block:: shell
echo /usr/local/lib64 | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
sudo ldconfig
@@ -175,7 +171,7 @@
Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
the installation directory of the shared library:
- .. code-block:: sh
+ .. code-block:: shell
export LD_LIBRARY_PATH=/usr/local/lib64
@@ -190,7 +186,8 @@
``PKG_CONFIG_PATH`` is configured properly (or if ``<LIBDIR>/pkgconfig`` is a default
search path), the command ``pkgconf --cflags --libs libndn-cxx`` will return all
necessary compile and link flags for the ndn-cxx library.
-- ``<BINDIR>/ndnsec``: command-line tool to manage NDN keys and certificates.
+- ``<BINDIR>/ndnsec``: command-line tool to manage NDN keys and certificates used by
+ ndn-cxx applications.
- ``<BINDIR>/ndnsec-*``: convenience aliases for ``ndnsec`` tools.
If configured with tests (``./waf configure --with-tests``), the above commands
@@ -204,13 +201,13 @@
available memory divided by 1.5 GB (e.g., ``./waf -j2`` for 3 GB of memory). This
should avoid memory thrashing and result in faster compilation.
-Build with examples
--------------------
+Building with examples
+----------------------
By default, the examples in the ``examples/`` directory will not be built. To enable
them, pass ``--with-examples`` during the configuration step:
-.. code-block:: sh
+.. code-block:: shell
./waf configure --with-examples
./waf
@@ -219,7 +216,7 @@
To run the examples:
-.. code-block:: sh
+.. code-block:: shell
# trivial producer app
./build/examples/producer
@@ -233,7 +230,7 @@
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``:
-.. code-block:: sh
+.. code-block:: shell
cp examples/consumer.cpp examples/my-new-app.cpp
... # edit examples/my-new-app.cpp with your preferred editor
@@ -242,39 +239,12 @@
sudo ldconfig # on Linux only
./build/examples/my-new-app
-Debug symbols
--------------
-
-The default compiler flags include debug symbols in binaries. This should provide
-more meaningful debugging information if ndn-cxx or your application crashes.
-
-If this is not desired, the default flags can be overridden to disable debug symbols.
-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
- sudo ./waf install
-
-Customizing the compiler
-------------------------
-
-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:
-
-.. code-block:: sh
-
- CXX=clang++ ./waf configure
-
Building the documentation
--------------------------
Tutorials and API documentation can be built using the following commands:
-.. code-block:: sh
+.. code-block:: shell
# Full set of documentation (tutorials + API) in build/docs
./waf docs
@@ -294,6 +264,33 @@
For further details, please refer to ``./waf --help``.
+Debug symbols
+-------------
+
+The default compiler flags include debug symbols in binaries. This should provide
+more meaningful debugging information if ndn-cxx or your application crashes.
+
+If this is not desired, the default flags can be overridden to disable debug symbols.
+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:: shell
+
+ CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
+ ./waf
+ sudo ./waf install
+
+Customizing the compiler
+------------------------
+
+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:
+
+.. code-block:: shell
+
+ CXX=clang++ ./waf configure
+
.. _Development build:
Development build
@@ -301,7 +298,7 @@
The following is the suggested build procedure for development builds:
-.. code-block:: sh
+.. code-block:: shell
./waf configure --debug --with-tests
./waf
@@ -312,7 +309,7 @@
will be treated as errors. This default behavior can be overridden by setting the
``CXXFLAGS`` environment variable before running ``./waf configure``, for example:
-.. code-block:: sh
+.. code-block:: shell
CXXFLAGS="-O1 -g3 -Wall" ./waf configure --debug --with-tests
./waf
diff --git a/docs/examples.rst b/docs/examples.rst
index cdc2df2..9185caf 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -1,7 +1,7 @@
Trivial applications
====================
-.. note::
+.. important::
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
diff --git a/docs/manpages/ndn-log.rst b/docs/manpages/ndn-log.rst
index f47dd1a..fc09e24 100644
--- a/docs/manpages/ndn-log.rst
+++ b/docs/manpages/ndn-log.rst
@@ -28,34 +28,30 @@
ndn-cxx logging facility provides a mechanism to manage the type of log messages
that are written by classifying log messages by severity levels. Listed below
-are the available log levels.
+are the available log levels:
-**Log Levels:**
-
-::
-
- TRACE
- DEBUG
- INFO
- WARN
- ERROR
- FATAL
+* TRACE
+* DEBUG
+* INFO
+* WARN
+* ERROR
+* FATAL
A message's severity level will determine whether the log is written. For instance,
if an application sets its log severity level to DEBUG, all messages marked with
DEBUG, or any of those below that level, are written. FATAL level logs are always
written.
-Setting NDN_LOG requires the following syntax with as many prefixes and
+Setting ``NDN_LOG`` requires the following syntax with as many prefixes and
corresponding loglevels as the user desires:
-.. code-block:: sh
+.. code-block:: shell
export NDN_LOG="<prefix1>=<loglevel1>:<prefix2>=<loglevel2>"
*Example:*
-.. code-block:: sh
+.. code-block:: shell
export NDN_LOG="ndn.*=DEBUG"
export NDN_LOG="ndn.UnixTransport=INFO"
@@ -69,14 +65,14 @@
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
+.. code-block:: shell
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
+.. code-block:: shell
export NDN_LOG="*=INFO:ndn.*=ERROR:ndn.UnixTransport=TRACE"
@@ -85,7 +81,7 @@
Setting the environment variable with sudo requires the application to be run
in the same command.
-.. code-block:: sh
+.. code-block:: shell
# Correct
sudo env NDN_LOG=logLevel ./ndn-application
diff --git a/docs/specs/signed-interest.rst b/docs/specs/signed-interest.rst
index 67a88b3..0ecb72b 100644
--- a/docs/specs/signed-interest.rst
+++ b/docs/specs/signed-interest.rst
@@ -114,7 +114,7 @@
Recipients of a signed interest may further check the timestamp and the uniqueness of the
signed interest (e.g., when the signed interest carries a command). In this case, a signed
-interest may be treated as invalid if :
+interest may be treated as invalid if:
- a valid signed Interest whose timestamp is **equal or later** than the timestamp of the
received one has been received before.
diff --git a/docs/tutorials/security-validator-config.rst b/docs/tutorials/security-validator-config.rst
index c35cb9e..c0bd332 100644
--- a/docs/tutorials/security-validator-config.rst
+++ b/docs/tutorials/security-validator-config.rst
@@ -1,8 +1,6 @@
Validator Configuration File Format
===================================
-.. contents::
-
You can set up a ``Validator`` via a configuration file. Next, we will show you how to
write a configuration file.
@@ -51,7 +49,7 @@
file-name "testbed-trust-anchor.cert"
}
-.. attention:: **The order of rules MATTERS!**
+.. important:: The order of rules MATTERS!
A rule can be broken into two parts:
@@ -96,7 +94,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.
-.. attention:: **A packet that satisfies all the filters may not be valid.**
+.. caution:: 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
@@ -382,24 +380,18 @@
}
If certificates under the directory might be changed during runtime, you can set a refresh
-period, such as
-
-::
+period::
trust-anchor
{
type dir
dir /usr/local/etc/ndn/keys
- refresh 1h ; refresh certificates every hour, other units include m (for minutes) and s (for seconds)
+ refresh 1h ; refresh certs every hour, other supported units are 'm' (for minutes) and 's' (for seconds)
}
-There is also a special trust anchor **any**. As long as such a trust-anchor is defined
+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.
-.. 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).
-
::
trust-anchor
@@ -407,6 +399,10 @@
type any
}
+.. danger::
+ This type of trust anchor is insecure. You should used it only when you want
+ to disable packet validation temporarily (e.g., debugging code, building a demo).
+
Example Configuration For NLSR
------------------------------