docs: improve formatting and document structure

Change-Id: I530d58f2700eb264855843021db32f568d373a1d

.github/workflows/ci.yml

@@ -53,7 +53,7 @@ jobs:
           - os: macos-12
             xcode: '13.4'
           - os: macos-12
-            xcode: '14.1'
+            xcode: '14.2'
     steps:
       - name: Set up Xcode
         uses: maxim-lobanov/setup-xcode@v1

.jenkins.d/00-deps.sh

@@ -21,7 +21,7 @@ set -x
 
 if [[ $ID == macos ]]; then
     if [[ -n $GITHUB_ACTIONS ]]; then
-        export HOMEBREW_NO_INSTALL_UPGRADE=1
+        export HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1
     fi
     brew update
     brew install --formula "${FORMULAE[@]}"

.waf-tools/default-compiler-flags.py

@@ -145,9 +145,9 @@ class GccBasicFlags(CompilerFlags):
         flags = super(GccBasicFlags, self).getDebugFlags(conf)
         flags['CXXFLAGS'] += ['-Og',
                               '-g3',
-                              '-pedantic',
                               '-Wall',
                               '-Wextra',
+                              '-Wpedantic',
                               '-Werror',
                               '-Wcatch-value=2',
                               '-Wextra-semi',
@@ -163,9 +163,9 @@ class GccBasicFlags(CompilerFlags):
         flags = super(GccBasicFlags, self).getOptimizedFlags(conf)
         flags['CXXFLAGS'] += ['-O2',
                               '-g',
-                              '-pedantic',
                               '-Wall',
                               '-Wextra',
+                              '-Wpedantic',
                               '-Wcatch-value=2',
                               '-Wextra-semi',
                               '-Wnon-virtual-dtor',

AUTHORS.md

@@ -1,8 +1,8 @@
 # NLSR Authors
 
-The following lists maintainers, primary developers, and all much-appreciated contributors to NLSR in alphabetic order.
+The following lists maintainers, primary developers, and all much-appreciated contributors to NLSR in alphabetical order.
 The specific contributions of individual authors can be obtained from the git history of the [official NLSR repository](https://github.com/named-data/NLSR).
-If you would like to become a contributor to the official repository, please follow the recommendations in https://github.com/named-data/.github/blob/master/CONTRIBUTING.md.
+If you would like to become a contributor to the official repository, please follow the recommendations in <https://github.com/named-data/.github/blob/master/CONTRIBUTING.md>.
 
 * Alexander Afanasyev <https://users.cs.fiu.edu/~afanasyev>
 * Adam Alyyan <https://github.com/a64adam>

COPYING.md

@@ -21,11 +21,10 @@ NLSR relies on third-party software, licensed under the following licenses:
 - The waf build system is licensed under the terms of the
   [BSD license](https://github.com/named-data/NLSR/blob/master/waf)
 
-
 The GPL license is provided below in this file.
-For more information, see http://www.gnu.org/licenses/
+For more information, see <https://www.gnu.org/licenses/>
 
-----------------------------------------------------------------------------------
+--------------------------------------------------------------------------------
 
 ### GNU GENERAL PUBLIC LICENSE
 

README-dev.md

@@ -1,5 +1,9 @@
-Requirements
+# Notes for NLSR developers
-------------
+
+If you are new to the NDN software community, please read the
+[Contributor's Guide](https://github.com/named-data/.github/blob/master/CONTRIBUTING.md).
+
+## Licensing requirements
 
 Contributions to NLSR must be licensed under GPL 3.0 or compatible license.  If you are
 choosing GPL 3.0, please use the following license boilerplate in all `.hpp` and `.cpp`
@@ -26,15 +30,13 @@ Include the following header in all `.hpp` and `.cpp` files:
      * NLSR, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
      */
 
-If you are affiliated with an NSF-supported NDN project institution,
+If you are affiliated with an NSF-supported NDN project institution, please use the [NDN Team License
-please use the [NDN Team License Boilerplate]
+Boilerplate](https://redmine.named-data.net/projects/nlsr/wiki/NDN_Team_License_Boilerplate_(NLSR)).
-(https://redmine.named-data.net/projects/nlsr/wiki/NDN_Team_License_Boilerplate_(NLSR)).
 
-Recommendations
+## Recommendations
----------------
 
-NLSR code is subject to the code style, defined here:
+NLSR code is subject to the code style defined
-https://redmine.named-data.net/projects/nfd/wiki/CodeStyle
+[here](https://redmine.named-data.net/projects/nfd/wiki/CodeStyle).
 
-NLSR Developer's guide can be found here:
+NLSR Developer's guide can be found
-https://github.com/named-data/NLSR/blob/developers-guide/NLSR-Developers-Guide.pdf
+[here](https://github.com/named-data/NLSR/blob/developers-guide/NLSR-Developers-Guide.pdf).

README.md

@@ -14,28 +14,25 @@ NLSR is a routing protocol in NDN that populates NDN's Routing Information Base.
 NLSR will continue to evolve alongside the Named Data Networking
 [protocol](https://named-data.net/doc/NDN-packet-spec/current/).
 
-NLSR is an open and free software package licensed under the GPL 3.0 license and free to
-all Internet users and developers.  For more information about the licensing details and
-limitations, refer to [`COPYING.md`](COPYING.md).
-
-NLSR is developed by the members of the [NSF-sponsored NDN project team](https://named-data.net/project/participants/).
-For more details, please refer to [`AUTHORS.md`](AUTHORS.md).
-Bug reports and feedback are highly appreciated and can be made through our
-[Redmine site](https://redmine.named-data.net/projects/nlsr/issues).
-
 The main design goal of NLSR is to provide a routing protocol to populate NDN's RIB.
 NLSR calculates the routing table using link-state or hyperbolic routing and produces
 multiple faces for each reachable name prefix in a single authoritative domain. NLSR
 will continue to evolve over time to include neighbor discovery and to become a full
 fledged inter-domain routing protocol for NDN.
 
+NLSR was mainly developed by members of the NSF-sponsored [NDN project team](
+https://named-data.net/project/participants/). See [`AUTHORS.md`](AUTHORS.md) for details.
+
+Bug reports and feedback are highly appreciated and can be submitted through the
+[NLSR issue tracker](https://redmine.named-data.net/projects/nlsr/issues).
+
 ## Source releases
 
 The source code and installation instructions are available at the following locations:
 
 - [Installation](https://named-data.net/doc/NLSR/current/INSTALL.html)
-- [Getting Started with NLSR](https://named-data.net/doc/NLSR/current/GETTING-STARTED.html)
+- [Getting started with NLSR](https://named-data.net/doc/NLSR/current/GETTING-STARTED.html)
-- [GitHub NLSR repository](https://github.com/named-data/NLSR)
+- [NLSR GitHub repository](https://github.com/named-data/NLSR)
 
 ## Additional resources
 
@@ -46,3 +43,8 @@ The source code and installation instructions are available at the following loc
 - [NLSR Mailing List](https://listserv.memphis.edu/scripts/wa.exe?SUBED1=NLSR-HELP-L&A=1)
 - [NLSR Mailing List Archives](https://listserv.memphis.edu/scripts/wa.exe?A0=NLSR-HELP-L)
 - [NLSR Developer's guide](https://github.com/named-data/NLSR/blob/developers-guide/NLSR-Developers-Guide.pdf)
+
+## License
+
+NLSR is free software distributed under the GNU General Public License version 3.
+See [`COPYING.md`](COPYING.md) for details.

docs/RELEASE-NOTES.rst

@@ -1,4 +0,0 @@
-Release Notes
-=============
-
-.. include:: release-notes-latest.rst

docs/conf.py

@@ -10,7 +10,7 @@ import sys
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'Named Data Link State Routing Protocol (NLSR)'
-copyright = 'Copyright © 2014-2022 Named Data Networking Project.'
+copyright = 'Copyright © 2014-2023 Named Data Networking Project.'
 author = 'Named Data Networking Project'
 
 # The short X.Y version.

docs/index.rst

@@ -1,29 +1,5 @@
-NLSR - Named Data Link State Routing Protocol
+NLSR: Named Data Link State Routing Protocol
-=============================================
+============================================
-
-NLSR is a routing protocol in NDN that populates NDN's Routing Information Base. NLSR will
-continue to evolve alongside the Named Data Networking `protocol
-<https://named-data.net/doc/NDN-packet-spec/current/>`_.
-
-NLSR is an open and free software package licensed under the GPL 3.0 license and free to
-all Internet users and developers. For more information about the licensing details and
-limitations, refer to `COPYING.md
-<https://github.com/named-data/NLSR/blob/master/COPYING.md>`_.
-
-NLSR is developed by the members of the `NSF-sponsored NDN project team
-<https://named-data.net/project/participants/>`_. For more details, please refer to
-`AUTHORS.md <https://github.com/named-data/NLSR/blob/master/AUTHORS.md>`_. Bug reports and
-feedback are highly appreciated and can be made through the `NLSR Wiki`_.
-
-The main design goal of NLSR is to provide a routing protocol to populate NDN's FIB. NLSR
-calculates the routing table using link-state or hyperbolic routing and produces multiple
-faces for each reachable name prefix in a single authoritative domain. NLSR will continue
-to evolve over time to include neighbor discovery and to become a full fledged
-inter-domain routing protocol for NDN.  The protocol design is presented in full detail in
-the `NLSR Paper`_.
-
-NLSR Documentation
-------------------
 
 .. toctree::
    :hidden:
@@ -33,47 +9,74 @@ NLSR Documentation
    INSTALL
    SECURITY-CONFIG
    ROUTER-CONFIG
-   RELEASE-NOTES
-   releases
-   manpages
    beginners-guide
+   manpages
+   release-notes
+   releases
 
--  :doc:`GETTING-STARTED`
+**NLSR** is a routing protocol for NDN that populates NDN's Routing Information Base.
--  :doc:`INSTALL`
+NLSR will continue to evolve alongside the Named Data Networking `protocol
--  :doc:`SECURITY-CONFIG`
+<https://named-data.net/doc/NDN-packet-spec/current/>`__.
--  :doc:`ROUTER-CONFIG`
+
--  :doc:`RELEASE-NOTES`
+The main design goal of NLSR is to provide a routing protocol to populate NDN's FIB. NLSR
--  :doc:`releases`
+calculates the routing table using link-state or hyperbolic routing and produces multiple
--  :doc:`manpages`
+faces for each reachable name prefix in a single authoritative domain. NLSR will continue
--  :doc:`beginners-guide`
+to evolve over time to include neighbor discovery and to become a full fledged
+inter-domain routing protocol for NDN.  The protocol design is presented in full detail in
+the `NLSR Paper`_.
+
+NLSR was mainly developed by members of the NSF-sponsored `NDN project team
+<https://named-data.net/project/participants/>`__.  See `AUTHORS.md
+<https://github.com/named-data/NLSR/blob/master/AUTHORS.md>`__ for details.
+
+Bug reports and feedback are highly appreciated and can be made through the `NLSR Redmine`_.
+
+Documentation
+-------------
+
+- :doc:`GETTING-STARTED`
+- :doc:`INSTALL`
+- :doc:`SECURITY-CONFIG`
+- :doc:`ROUTER-CONFIG`
+- :doc:`beginners-guide`
+- :doc:`manpages`
+- :doc:`release-notes`
+- :doc:`releases`
 
 Downloading
 -----------
 
--  `Source code git repository <https://github.com/named-data/NLSR>`_
+- `Source code git repository <https://github.com/named-data/NLSR>`__
 
 NLSR mailing list
 -----------------
 
--  `NLSR Mailing List`_
+- `NLSR Mailing List`_
-
+- `NLSR Mailing List Archives`_
--  `NLSR Mailing List Archives`_
 
 `Sign up`_ is needed to post to the list or access the archives.
 
-Additional information
+Additional resources
-----------------------
+--------------------
 
--  `NLSR Wiki`_
+- `NLSR Wiki`_
 
--  `NLSR Redmine`_
+- `NLSR Redmine`_
-   Feature requests and bug reports
+  Feature requests and bug reports
 
--  `NLSR Paper`_
+- `NLSR Paper`_
-   Detailed explanation of the NLSR design
+  Detailed explanation of NLSR's design
 
--  `NLSR Developer's Guide`_
+- `NLSR Developer's Guide`_
-   For NLSR Development
+  For NLSR development
+
+- `API documentation (doxygen) <doxygen/annotated.html>`__
+
+License
+-------
+
+NLSR is free software distributed under the GNU General Public License version 3.
+See `COPYING.md <https://github.com/named-data/NLSR/blob/master/COPYING.md>`__ for details.
 
 .. _NLSR Wiki: https://redmine.named-data.net/projects/nlsr/wiki
 .. _NLSR Paper: https://named-data.net/wp-content/uploads/2016/01/ndn-0037-1-nlsr.pdf

docs/manpages/nlsrc.rst

@@ -79,18 +79,15 @@ Notes
 When security is enabled, NLSR will not be allowed to successfully
 advertise/withdraw names without first setting a default identity of operator.
 If default identity is not set as operator, the user will be presented with the
-error message: “Name prefix update error (code: 403)”. To remedy this
+error message: "Name prefix update error (code: 403)". To remedy this
-issue, use command 'ndn-sec-default'.
+issue, use the command ``ndnsec set-default``. Example::
 
-Example:
+  ndnsec set-default /ndn/a-site/%C1.Operator/op
-
-  ndnsec-set-default /ndn/a-site/%C1.Operator/op
 
 Exit Status
 -----------
 
-nlsrc exits with one of the following values:
+nlsrc exits with one of the following values::
-::
 
   0     nlsrc exited successfully
   >0    An error occurred

docs/release-notes-latest.rst

@@ -1 +0,0 @@
-release-notes/release-notes-0.6.0.rst

docs/release-notes.rst

@@ -0,0 +1,4 @@
+Release Notes
+=============
+
+.. include:: release-notes/release-notes-0.6.0.rst

docs/release-notes/release-notes-0.5.2.rst

@@ -3,15 +3,16 @@ NLSR version 0.5.2
 
 **Breaking Changes**
 
-The following breaking changes makes this release incompatible with the previous version.
+The following breaking changes make this release incompatible with the previous version.
-- Use latest PSync version 0.2.0, sync data compression enabled in full sync by default (:issue:`5061`, :issue:`4917`)
+
-- Use the double encoding/decoding functions for hyperbolic coordinates (:issue:`4615`)
+- Use PSync version 0.2.0, sync data compression in full sync is enabled by default (:issue:`5061`, :issue:`4917`)
+- Use the floating point encoding/decoding functions for hyperbolic coordinates (:issue:`4615`)
 
 **New Features**
 
 - Handle zero cost links in Link State Routing (:issue:`4978`)
 
-**Improvements and Bug Fixes**:
+**Improvements and Bug Fixes**
 
 - Remove support for old combined seq no file (:issue:`4143`)
 - Sync common test infrastructure with ndn-cxx

docs/release-notes/release-notes-0.6.0.rst

@@ -1,10 +1,12 @@
 NLSR version 0.6.0
-++++++++++++++++++
+------------------
 
-**Improvements and Bug Fixes**
+Improvements and bug fixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- **breaking change** Major changes in the TLV structure and classes. Reduced codebase size and
+- *(breaking change)* Major changes in the TLV structure and classes. Reduced codebase size and
-  improved compilation times. LSA de/serialize functions are replaced by wireEncode/Decode. Updated LSA
+  improved compilation times. LSA de/serialize functions are replaced by wireEncode/Decode.
-  wire formats and TLV assignments. Updated nlsrc to print using the new encoding. (:issue:`4787`, :issue:`5116`)
+  Updated LSA wire formats and TLV assignments. Updated nlsrc to print using the new encoding.
+  (:issue:`4787`, :issue:`5116`)
 - LSDB refactor: switch to ``boost::multi_index`` to replace 3 LSA lists (:issue:`4127`)
 - Fix wrong reaction on hello Interest timeout (:issue:`5139`)

docs/releases.rst

@@ -1,5 +1,5 @@
 NLSR Versions
-+++++++++++++
+=============
 
 .. toctree::
    :glob: