docs: improve formatting and document structure
Change-Id: I530d58f2700eb264855843021db32f568d373a1d
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b551e45..f328d39 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -53,7 +53,7 @@
- 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
diff --git a/.jenkins.d/00-deps.sh b/.jenkins.d/00-deps.sh
index 9b1e073..c114f8d 100755
--- a/.jenkins.d/00-deps.sh
+++ b/.jenkins.d/00-deps.sh
@@ -21,7 +21,7 @@
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[@]}"
diff --git a/.waf-tools/default-compiler-flags.py b/.waf-tools/default-compiler-flags.py
index 4debb4e..3a7bf66 100644
--- a/.waf-tools/default-compiler-flags.py
+++ b/.waf-tools/default-compiler-flags.py
@@ -145,9 +145,9 @@
flags = super(GccBasicFlags, self).getDebugFlags(conf)
flags['CXXFLAGS'] += ['-Og',
'-g3',
- '-pedantic',
'-Wall',
'-Wextra',
+ '-Wpedantic',
'-Werror',
'-Wcatch-value=2',
'-Wextra-semi',
@@ -163,9 +163,9 @@
flags = super(GccBasicFlags, self).getOptimizedFlags(conf)
flags['CXXFLAGS'] += ['-O2',
'-g',
- '-pedantic',
'-Wall',
'-Wextra',
+ '-Wpedantic',
'-Wcatch-value=2',
'-Wextra-semi',
'-Wnon-virtual-dtor',
diff --git a/AUTHORS.md b/AUTHORS.md
index 1dce9f7..b9bdca0 100644
--- a/AUTHORS.md
+++ b/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>
diff --git a/COPYING.md b/COPYING.md
index 661a055..252444b 100644
--- a/COPYING.md
+++ b/COPYING.md
@@ -21,11 +21,10 @@
- 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
diff --git a/README-dev.md b/README-dev.md
index b7b3958..27aa479 100644
--- a/README-dev.md
+++ b/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 @@
* 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,
-please use the [NDN Team License Boilerplate]
-(https://redmine.named-data.net/projects/nlsr/wiki/NDN_Team_License_Boilerplate_(NLSR)).
+If you are affiliated with an NSF-supported NDN project institution, please use the [NDN Team License
+Boilerplate](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:
-https://redmine.named-data.net/projects/nfd/wiki/CodeStyle
+NLSR code is subject to the code style defined
+[here](https://redmine.named-data.net/projects/nfd/wiki/CodeStyle).
-NLSR Developer's guide can be found here:
-https://github.com/named-data/NLSR/blob/developers-guide/NLSR-Developers-Guide.pdf
+NLSR Developer's guide can be found
+[here](https://github.com/named-data/NLSR/blob/developers-guide/NLSR-Developers-Guide.pdf).
diff --git a/README.md b/README.md
index 25cee7d..6ce446b 100644
--- a/README.md
+++ b/README.md
@@ -14,28 +14,25 @@
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)
-- [GitHub NLSR repository](https://github.com/named-data/NLSR)
+- [Getting started with NLSR](https://named-data.net/doc/NLSR/current/GETTING-STARTED.html)
+- [NLSR GitHub repository](https://github.com/named-data/NLSR)
## Additional resources
@@ -46,3 +43,8 @@
- [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.
diff --git a/docs/RELEASE-NOTES.rst b/docs/RELEASE-NOTES.rst
deleted file mode 100644
index 04e2f84..0000000
--- a/docs/RELEASE-NOTES.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-Release Notes
-=============
-
-.. include:: release-notes-latest.rst
diff --git a/docs/conf.py b/docs/conf.py
index a7b4832..1e61a46 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -10,7 +10,7 @@
# 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.
diff --git a/docs/index.rst b/docs/index.rst
index 27a28ba..fa1ee00 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,29 +1,5 @@
-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
-------------------
+NLSR: Named Data Link State Routing Protocol
+============================================
.. toctree::
:hidden:
@@ -33,47 +9,74 @@
INSTALL
SECURITY-CONFIG
ROUTER-CONFIG
- RELEASE-NOTES
- releases
- manpages
beginners-guide
+ manpages
+ release-notes
+ releases
-- :doc:`GETTING-STARTED`
-- :doc:`INSTALL`
-- :doc:`SECURITY-CONFIG`
-- :doc:`ROUTER-CONFIG`
-- :doc:`RELEASE-NOTES`
-- :doc:`releases`
-- :doc:`manpages`
-- :doc:`beginners-guide`
+**NLSR** is a routing protocol for 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/>`__.
+
+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 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 Archives`_
+- `NLSR Mailing List`_
+- `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`_
- Feature requests and bug reports
+- `NLSR Redmine`_
+ Feature requests and bug reports
-- `NLSR Paper`_
- Detailed explanation of the NLSR design
+- `NLSR Paper`_
+ Detailed explanation of NLSR's design
-- `NLSR Developer's Guide`_
- For NLSR Development
+- `NLSR Developer's Guide`_
+ 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
diff --git a/docs/manpages/nlsrc.rst b/docs/manpages/nlsrc.rst
index f91706b..81d92f2 100644
--- a/docs/manpages/nlsrc.rst
+++ b/docs/manpages/nlsrc.rst
@@ -79,18 +79,15 @@
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
-issue, use command 'ndn-sec-default'.
+error message: "Name prefix update error (code: 403)". To remedy this
+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
diff --git a/docs/release-notes-latest.rst b/docs/release-notes-latest.rst
deleted file mode 120000
index cbbc128..0000000
--- a/docs/release-notes-latest.rst
+++ /dev/null
@@ -1 +0,0 @@
-release-notes/release-notes-0.6.0.rst
\ No newline at end of file
diff --git a/docs/release-notes.rst b/docs/release-notes.rst
new file mode 100644
index 0000000..7a816ba
--- /dev/null
+++ b/docs/release-notes.rst
@@ -0,0 +1,4 @@
+Release Notes
+=============
+
+.. include:: release-notes/release-notes-0.6.0.rst
diff --git a/docs/release-notes/release-notes-0.5.2.rst b/docs/release-notes/release-notes-0.5.2.rst
index aa4c526..d65d507 100644
--- a/docs/release-notes/release-notes-0.5.2.rst
+++ b/docs/release-notes/release-notes-0.5.2.rst
@@ -3,15 +3,16 @@
**Breaking Changes**
-The following breaking changes makes 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`)
+The following breaking changes make this release incompatible with the previous version.
+
+- 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
diff --git a/docs/release-notes/release-notes-0.6.0.rst b/docs/release-notes/release-notes-0.6.0.rst
index 1701c67..04c17c1 100644
--- a/docs/release-notes/release-notes-0.6.0.rst
+++ b/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
- improved compilation times. LSA de/serialize functions are replaced by wireEncode/Decode. Updated LSA
- wire formats and TLV assignments. Updated nlsrc to print using the new encoding. (:issue:`4787`, :issue:`5116`)
+- *(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 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`)
diff --git a/docs/releases.rst b/docs/releases.rst
index 39b1403..96ed2ea 100644
--- a/docs/releases.rst
+++ b/docs/releases.rst
@@ -1,5 +1,5 @@
NLSR Versions
-+++++++++++++
+=============
.. toctree::
:glob: