Minor README improvements; fix outdated URLs

Change-Id: Ia57f83892471ad85a2301ba4c8ab3df144581000

AUTHORS.md

@@ -2,7 +2,7 @@
 
 The following lists maintainers, primary developers, and all much-appreciated contributors to ndn-tools in alphabetical order.
 The specific contributions of individual authors can be obtained from the git history of the [official ndn-tools repository](https://github.com/named-data/ndn-tools).
-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/main/CONTRIBUTING.md>.
 
 * Jerald Paul Abraham <https://cs.arizona.edu/~jeraldabraham>
 * ***(Maintainer)*** Alexander Afanasyev <https://users.cs.fiu.edu/~afanasyev>

INSTALL.md

@@ -4,17 +4,15 @@ This document describes how to build and install ndn-tools.
 
 ## Prerequisites
 
-- Install the [ndn-cxx](https://named-data.net/doc/ndn-cxx/current/) library and its prerequisites.
+* Install the [ndn-cxx](https://github.com/named-data/ndn-cxx) library and its dependencies.
-  Please see [Getting Started with ndn-cxx](https://named-data.net/doc/ndn-cxx/current/INSTALL.html)
+  Check out [the documentation](https://docs.named-data.net/ndn-cxx/current/INSTALL.html) for
-  for instructions.
+  detailed installation instructions. All platforms supported by ndn-cxx are also supported
-  All operating systems and compilers supported by ndn-cxx are also supported by ndn-tools.
+  by ndn-tools.
 
   *Note*: If you have installed ndn-cxx from a binary package, please make sure the development
   headers are installed (e.g., if using Ubuntu PPA, the `libndn-cxx-dev` package is needed).
 
-- `libpcap`
+* Install `libpcap` (except on macOS where it is provided by the base system).
-
-  Comes with the base system on macOS.
 
   On Debian and Ubuntu:
 

README-dev.md

@@ -3,7 +3,7 @@
 ## Licensing Requirements
 
 Contributions to ndn-tools must be licensed under the GPL 3.0 or a compatible license.
-If you choose GPL 3.0, include the following license boilerplate into all C++ code files:
+If you choose GPL 3.0, insert the following license boilerplate into all C++ source files:
 
     /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
     /*
@@ -57,7 +57,7 @@ and placed in the [`manpages`](manpages) directory.
 ## Code Guidelines
 
 C++ code should conform to the
-[ndn-cxx code style](https://named-data.net/doc/ndn-cxx/current/code-style.html).
+[ndn-cxx code style](https://docs.named-data.net/ndn-cxx/current/code-style.html).
 
 ### Namespace
 
@@ -83,36 +83,38 @@ subdirectory.
 
 Example:
 
-    namespace ndn {
+```cpp
-    namespace foo {
+namespace ndn {
+namespace foo {
 
-    class Bar
+class Bar
-    {
+{
-    public:
+public:
-      explicit
+  explicit
-      Bar(Face& face);
+  Bar(Face& face);
 
-      void
+  void
-      run();
+  run();
-    };
+};
 
-    static int
+static int
-    main(int argc, char* argv[])
+main(int argc, char* argv[])
-    {
+{
-      Face face;
+  Face face;
-      Bar program(face);
+  Bar program(face);
-      program.run();
+  program.run();
-      return 0;
+  return 0;
-    }
+}
 
-    } // namespace foo
+} // namespace foo
-    } // namespace ndn
+} // namespace ndn
 
-    int
+int
-    main(int argc, char* argv[])
+main(int argc, char* argv[])
-    {
+{
-      return ndn::foo::main(argc, argv);
+  return ndn::foo::main(argc, argv);
-    }
+}
+```
 
 ### Command Line Arguments
 

README.md

@@ -5,16 +5,16 @@
 ![Language](https://img.shields.io/badge/C%2B%2B-17-blue)
 ![Latest version](https://img.shields.io/github/v/tag/named-data/ndn-tools?label=Latest%20version)
 
-**ndn-tools** is a collection of basic tools for [Named Data Networking](https://named-data.net/).
+This repository contains a collection of basic tools for [Named Data Networking (NDN)](https://named-data.net/).
-Tools in this collection include:
+The tools currently included are:
 
-* [peek](tools/peek): transmit a single Interest/Data packet between a consumer
+* [**peek**](tools/peek): transmit a single Interest/Data packet between a consumer
   and a producer
-* [chunks](tools/chunks): segmented file transfer between a consumer and a producer
+* [**chunks**](tools/chunks): segmented file transfer between a consumer and a producer
-* [ping](tools/ping): test reachability between two NDN nodes
+* [**ping**](tools/ping): test reachability between two NDN nodes
-* [dump](tools/dump): capture and analyze live traffic on an NDN network
+* [**dump**](tools/dump): capture and analyze live traffic on an NDN network
-* [dissect](tools/dissect): inspect the TLV structure of an NDN packet
+* [**dissect**](tools/dissect): inspect the TLV structure of an NDN packet
-* [dissect-wireshark](tools/dissect-wireshark): Wireshark extension to inspect
+* [**dissect-wireshark**](tools/dissect-wireshark): Wireshark extension to inspect
   the TLV structure of NDN packets
 
 ## Installation
@@ -28,12 +28,13 @@ Please submit any bug reports or feature requests to the
 
 ## Contributing
 
-We greatly appreciate contributions to ndn-tools. If you are new to the NDN
+Contributions to ndn-tools are greatly appreciated and can be made through our
-software community, please read [`README-dev.md`](README-dev.md) and the
+[Gerrit code review site](https://gerrit.named-data.net/).
-[Contributor's Guide](https://github.com/named-data/.github/blob/master/CONTRIBUTING.md)
+If you are new to the NDN software community, please read our
-to get started.
+[Contributor's Guide](https://github.com/named-data/.github/blob/main/CONTRIBUTING.md)
+and [`README-dev.md`](README-dev.md) to get started.
 
 ## License
 
-ndn-tools is an open source project licensed under the GPL version 3.
+ndn-tools is free software distributed under the GNU General Public License version 3.
-See [`COPYING.md`](COPYING.md) for more information.
+See [`COPYING.md`](COPYING.md) for details.

manpages/conf.py

@@ -7,7 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'NDN Essential Tools'
-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.

manpages/ndnputchunks.rst

@@ -15,7 +15,7 @@ and makes it available as NDN Data segments.
 Version and segment number components are appended to the specified *name* as needed,
 according to the `NDN naming conventions`_.
 
-.. _NDN naming conventions: https://named-data.net/publications/techreports/ndn-tr-22-2-ndn-memo-naming-conventions/
+.. _NDN naming conventions: https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/
 
 Options
 -------

tools/chunks/README.md

@@ -4,8 +4,8 @@
 
 * **ndnputchunks** is a producer program that reads a file from the standard input, and makes
   it available as a set of NDN Data segments. It appends version and segment number components
-  to the specified name as needed, according to the
+  to the specified name as needed, according to the [NDN naming conventions](
-  [NDN naming conventions](https://named-data.net/publications/techreports/ndn-tr-22-2-ndn-memo-naming-conventions/).
+  https://named-data.net/publications/techreports/ndn-tr-22-3-ndn-memo-naming-conventions/).
 
 * **ndncatchunks** is a consumer program that fetches Data segments of a file, optionally
   discovering the latest version of the file, and writes the content of the retrieved file to
@@ -18,7 +18,7 @@ number will be used, without any version discovery process. Otherwise, discovery
 be sent out to fetch metadata of the solicited content from which the Data version will be resolved.
 For more information about the packet format and naming conventions of Interest and Data packets
 used for version discovery in ndncatchunks, please refer to:
-[Realtime Data Retrieval (RDR) protocol wiki page](https://redmine.named-data.net/projects/ndn-tlv/wiki/RDR)
+[Realtime Data Retrieval (RDR) protocol](https://redmine.named-data.net/projects/ndn-tlv/wiki/RDR).
 
 ## Interest pipeline types in ndncatchunks
 
@@ -32,7 +32,7 @@ used for version discovery in ndncatchunks, please refer to:
 * `cubic`: adjusts the window size similar to the TCP CUBIC algorithm.
            For details about both aimd and cubic please refer to:
            [A Practical Congestion Control Scheme for Named Data
-           Networking](https://conferences2.sigcomm.org/acm-icn/2016/proceedings/p21-schneider.pdf)
+           Networking](https://conferences2.sigcomm.org/acm-icn/2016/proceedings/p21-schneider.pdf).
 
 The default Interest pipeline type is `cubic`.
 

tools/dissect-wireshark/README.md

@@ -1,19 +1,18 @@
-NDN Packet Dissector for Wireshark
+# NDN Packet Dissector for Wireshark
-==================================
 
-**NDN packet dissector requires at least version 1.12.6 of Wireshark with LUA support enabled**
+*NOTE: The dissector requires at least version 1.12.6 of Wireshark with LUA support enabled.*
 
-The dissection of [Named Data Networking (NDN) packets](http://named-data.net/doc/ndn-tlv/) is
+The dissection of [NDN packets](https://docs.named-data.net/NDN-packet-spec/current/)
-supported in the following cases:
+is supported in the following cases:
 
-- NDN packets are encapsulated in IPv4/IPv6 UDP packets with source or destination port
+- NDN packets are encapsulated in IPv4/IPv6 UDP datagrams with source or destination
-  6363 or 56363.
+  port 6363 or 56363.
 
 - NDN packets are encapsulated in IPv4/IPv6 TCP segments with source or destination
   port 6363.
 
-- NDN packets are encapsulated in IPv4/IPv6 TCP/HTTP WebSocket packets with source or
+- NDN packets are encapsulated in IPv4/IPv6 WebSocket packets with source or destination
-  destination port 9696.
+  port 9696.
 
 - NDN packets are encapsulated in Ethernet frames with EtherType 0x8624.
 
@@ -56,11 +55,15 @@ On some platforms, it may also be installed in `/usr/share/ndn-dissect-wireshark
 `/opt/local/share/ndn-dissect-wireshark`.  To enable the dissector for Wireshark session,
 use `-X` command line option, specifying the full path to the `ndn.lua` script:
 
-    wireshark -X lua_script:/usr/local/share/ndn-dissect-wireshark/ndn.lua
+```shell
+wireshark -X lua_script:/usr/local/share/ndn-dissect-wireshark/ndn.lua
+```
 
 Similarly, NDN packets dissector can be enabled when using `tshark`:
 
-    tshark shark -X lua_script:/usr/local/share/ndn-dissect-wireshark/ndn.lua
+```shell
+tshark shark -X lua_script:/usr/local/share/ndn-dissect-wireshark/ndn.lua
+```
 
 To enable NDN packets dissector for all future Wireshark sessions, you can create/edit
 Wireshark's `init.lua` script, which located in `/usr/share/wireshark`,
@@ -68,8 +71,9 @@ Wireshark's `init.lua` script, which located in `/usr/share/wireshark`,
 or similar location depending on the platform and the way Wireshark is installed.  The
 `dofile` command should be added to the end of `init.lua` file:
 
-    -- dofile("/full/path/to/ndn.lua")
+```lua
-    dofile("/usr/local/share/ndn-dissect-wireshark/ndn.lua")
+dofile("/usr/local/share/ndn-dissect-wireshark/ndn.lua")
+```
 
 For more detailed information about how to use Lua refer to [Lua wiki](https://wiki.wireshark.org/Lua).
 
@@ -78,26 +82,26 @@ For more detailed information about how to use Lua refer to [Lua wiki](https://w
 Due to security issues, customized lua scripts are not allowed to be loaded when Wireshark
 is started with root privileges.  There are two workarounds:
 
-- run Wireshark, `dumpcap`, or `tcpdump` with root privileges to capture traffic to a file, later
+- Run `dumpcap` or `tcpdump` with root privileges to capture traffic to a file, and later
-  running Wireshark without root privileges and to analyze the captured traffic.
+  run Wireshark *without* root privileges to analyze the captured traffic.
 
-- (beware of potential security implications) allow non-root users to capture packets:
+- Allow non-root users to capture packets (beware of potential security implications!)
 
-  * On Linux platform, you can use `setcap`
+  * On Linux, you can use `setcap`:
 
-          sudo setcap cap_net_raw,cap_net_admin=eip /full/path/to/wireshark
+        sudo setcap cap_net_raw,cap_net_admin=eip /full/path/to/wireshark
 
-      You may need to install a package to use setcap (e.g., `sudo apt-get install libcap2-bin` on Ubuntu)
+    You may need to install a package to use `setcap` (e.g., `sudo apt install libcap2-bin` on Ubuntu)
 
-  * On Debian/Ubuntu Linux, capturing traffic with Wireshark by a non-root user can be enabled by adding
+  * On Debian/Ubuntu Linux, capturing traffic with Wireshark by a non-root user can be enabled by
-    this user to the `wireshark` group.
+    adding the user to the `wireshark` group.
 
-    See [Wireshark Debian README](http://anonscm.debian.org/viewvc/collab-maint/ext-maint/wireshark/trunk/debian/README.Debian?view=markup)
+    See Debian's [README file](https://salsa.debian.org/debian/wireshark/-/blob/debian/master/debian/README.Debian)
-    for more details.
+    for details.
 
-  * On OSX platform, `/dev/bpf*` devices need to be assigned proper permissions
+  * On macOS, `/dev/bpf*` devices need to be assigned proper permissions.
 
-    Automatically using ChmodBPF app
+    Automatically using ChmodBPF app:
 
         curl https://bugs.wireshark.org/bugzilla/attachment.cgi?id=3373 -o ChmodBPF.tar.gz
         tar zxvf ChmodBPF.tar.gz

tools/dissect-wireshark/ndn.lua

@@ -1,4 +1,4 @@
--- Copyright (c) 2015-2019,  Regents of the University of California.
+-- Copyright (c) 2015-2023, Regents of the University of California.
 --
 -- This file is part of ndn-tools (Named Data Networking Essential Tools).
 -- See AUTHORS.md for complete list of ndn-tools authors and contributors.
@@ -173,7 +173,7 @@ function getGenericBlockInfo(block)
    local name = ""
 
    -- TODO: Properly format informational message based type value reservations
-   -- (https://named-data.net/doc/NDN-packet-spec/current/types.html#tlv-type-number-reservations)
+   -- (https://docs.named-data.net/NDN-packet-spec/current/types.html#reserved-ranges)
    if (block.type <= AppPrivateBlock1) then
       name = "Unrecognized from the reserved range " .. 0 .. "-" .. AppPrivateBlock1 .. ""
    elseif (AppPrivateBlock1 < block.type and block.type < AppPrivateBlock2) then

tools/dissect/dissector.cpp

@@ -1,6 +1,6 @@
 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
 /*
- * Copyright (c) 2013-2022, Regents of the University of California.
+ * Copyright (c) 2013-2023, Regents of the University of California.
  *
  * This file is part of ndn-tools (Named Data Networking Essential Tools).
  * See AUTHORS.md for complete list of ndn-tools authors and contributors.
@@ -74,7 +74,7 @@ Dissector::printBranches()
   }
 }
 
-// https://named-data.net/doc/NDN-packet-spec/current/types.html
+// https://docs.named-data.net/NDN-packet-spec/current/types.html
 static const std::map<uint32_t, std::string_view> TLV_DICT = {
   {tlv::Interest                        , "Interest"},
   {tlv::Data                            , "Data"},

tools/dump/README.md

@@ -5,9 +5,10 @@ and displays brief information about captured packets.
 
 Usage example:
 
-1. start NFD on local machine
+1. start NFD on the local machine
-2. create an IPv4 UDP tunnel to a remote machine
+2. create a UDP tunnel to a remote machine
-3. cause some traffic going on the tunnel
+3. run `sudo ndndump`
-4. execute `sudo ndndump`
+4. cause some NDN traffic to be sent/received on the tunnel
+5. observe the output of `ndndump`
 
 For more information, consult the manpage.

tools/peek/README.md

@@ -8,7 +8,7 @@
 Usage example:
 
 1. start NFD
-2. execute `echo 'HELLO WORLD' | ndnpoke /localhost/demo/hello`
+2. run `echo 'HELLO WORLD' | ndnpoke /localhost/demo/hello`
-3. in another terminal, execute `ndnpeek -p /localhost/demo/hello`
+3. in another terminal, run `ndnpeek -p /localhost/demo/hello`
 
-For more information, consult the manpages of these programs.
+For more information on these programs, consult their respective manpages.

tools/ping/README.md

@@ -2,47 +2,48 @@
 
 ## Introduction
 
-**ndnping** and **ndnpingserver** are reachability testing tools for
+**ndnping** and **ndnpingserver** are reachability testing tools for NDN. They can be used
-[Named Data Networking](http://named-data.net). They test the reachability between two nodes. The
+to test the network reachability between two nodes. The client sends an Interest intended
-client sends an Interest intended for a node running **ndnpingserver**. The ping server then sends
+for a node running **ndnpingserver**. The server then sends Data in response. The client
-Data in response. The client then calculates the roundtrip time for the Interest-Data exchange, or
+then calculates the roundtrip time for the Interest-Data exchange, or marks it as a timeout
-marks it as a timeout if the Data is not received within the timeout period.
+if the Data packet is not received within the timeout period.
 
-## Using the Client
+## Using the client
 
-The client can be invoked by calling **ndnping** with a name to ping. For example, to ping
+The client can be invoked by calling `ndnping` with a name to ping. For example, to ping
-`/edu/arizona`, one would execute:
+`/edu/arizona`, one would run:
 
     ndnping /edu/arizona
 
-There are also a variety of options to control the behavior of the ping client. For example, to
+There are also a variety of options to control the behavior of the ping client. For example,
-send only four pings to `/edu/arizona`, displaying a timestamp with each received Data or
+to send only four pings to `/edu/arizona`, displaying a timestamp with each received Data or
 timeout, type:
 
     ndnping -c 4 -t /edu/arizona
 
 A list of the available options can be found with `man ndnping`.
 
-## Using the Server
+## Using the server
 
-The server can be invoked by calling **ndnpingserver** with a name to listen for pings to. For
+The server can be invoked by calling `ndnpingserver` with a name to listen for pings to. For
-example, to listen for pings to `/edu/arizona`, one would execute:
+example, to listen for pings to `/edu/arizona`, one would run:
 
     ndnpingserver /edu/arizona
 
-There are also a variety of options to control the behavior of the ping server. For example, to
+There are also a variety of options to control the behavior of the ping server. For example,
-satisfy only 4 ping requests before exiting, execute the following:
+to satisfy only 4 ping requests before exiting, run the following:
 
     ndnpingserver -p 4 /edu/arizona
 
 A list of the available options can be found with `man ndnpingserver`.
 
-## ndnping Protocol
+## NDN ping protocol
 
 This section briefly describes ndnping's protocol, in order to allow alternate implementations
 to be compatible with this implementation.
+
 The current protocol version is **ndnping protocol version 1**.
-This version number will be incremented in case there's an incompatible change.
+This version number will be incremented whenever there is an incompatible change.
 
 ### Probe Interests