Improved markdown formatting of the manual

2026-06-08 14:11:53 -07:00 · 2026-05-23 09:53:38 +02:00
parent 2c9b794182
commit fa7699a37d
7 changed files with 24 additions and 95 deletions
@@ -383,11 +383,7 @@ For a one-shot installation of Reticulum, without globally enabling the ``break-
    pip install rns --break-system-packages

 .. note::
-   The ``--break-system-packages`` directive is a somewhat misleading choice
-   of words. Setting it will of course not break any system packages, but will simply
-   allow installing ``pip`` packages user- and system-wide. While this *could* in rare
-   cases lead to version conflicts, it does not generally pose any problems, especially
-   not in the case of installing Reticulum.
+   The ``--break-system-packages`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing ``pip`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.


 MacOS
@@ -424,12 +420,7 @@ OpenWRT
 On OpenWRT systems with sufficient storage and memory, you can install Reticulum and related utilities using the `opkg` package manager and `pip`.

 .. note::
-
-   At the time of releasing this manual, work is underway to create pre-built
-   Reticulum packages for OpenWRT, with full configuration, service
-   and ``uci`` integration. Please see the `feed-reticulum <https://github.com/gretel/feed-reticulum>`_
-   and `reticulum-openwrt <https://github.com/gretel/reticulum-openwrt>`_
-   repositories for more information.
+   At the time of releasing this manual, work is underway to create pre-built Reticulum packages for OpenWRT, with full configuration, service and ``uci`` integration. Please see the `feed-reticulum <https://github.com/gretel/feed-reticulum>`_ and `reticulum-openwrt <https://github.com/gretel/reticulum-openwrt>`_ repositories for more information.

 To install Reticulum on OpenWRT, first log into a command line session, and then use the following instructions:

@@ -445,7 +436,6 @@ To install Reticulum on OpenWRT, first log into a command line session, and then
   rnsd -vvv

 .. note::
-   
   The above instructions have been verified and tested on OpenWRT 21.02 only. It is likely that other versions may require slightly altered installation commands or package names. You will also need enough free space in your overlay FS, and enough free RAM to actually run Reticulum and any related programs and utilities.

 Depending on your device configuration, you may need to adjust firewall rules for Reticulum connectivity to and from your device to work. Until proper packaging is ready, you will also need to manually create a service or startup script to automatically laucnh Reticulum at boot time.
@@ -188,9 +188,7 @@ As an example, an announce in a simple messenger application might contain the f

 With this information, any Reticulum node that receives it will be able to reconstruct an outgoing destination to securely communicate with that destination. You might have noticed that there is one piece of information lacking to reconstruct full knowledge of the announced destination, and that is the aspect names of the destination. These are intentionally left out to save bandwidth, since they will be implicit in almost all cases. The receiving application will already know them. If a destination name is not entirely implicit, information can be included in the application specific data part that will allow the receiver to infer the naming.

-It is important to note that announces will be forwarded throughout the network according to a
-certain pattern. This will be detailed in the section
-:ref:`The Announce Mechanism in Detail<understanding-announce>`.
+It is important to note that announces will be forwarded throughout the network according to a certain pattern. This will be detailed in the section :ref:`The Announce Mechanism in Detail<understanding-announce>`.

 In Reticulum, destinations are allowed to move around the network at will. This is very different from protocols such as IP, where an address is always expected to stay within the network segment it was assigned in. This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and still become reachable. To update its reachability, a destination simply needs to send an announce on any networks it is part of. After a short while, it will be globally reachable in the network.

@@ -281,15 +279,9 @@ Once an announce has reached a transport node in the network, any other node in
 According to these rules, an announce will propagate throughout the network in a predictable way, and make the announced destination reachable in a short amount of time. Fast networks that have the capacity to process many announces can reach full convergence very quickly, even when constantly adding new destinations. Slower segments of such networks might take a bit longer to gain full knowledge about the wide and fast networks they are connected to, but can still do so over time, while prioritising full and quickly converging end-to-end connectivity for their local, slower segments.

 .. tip::
+    Even very slow networks, that simply don't have the capacity to ever reach *full* convergence will generally still be able to reach **any other destination on any connected segments**, since interconnecting transport nodes will prioritize announces into the slower segments that are actually requested by nodes on these.

-    Even very slow networks, that simply don't have the capacity to ever reach *full* convergence
-    will generally still be able to reach **any other destination on any connected segments**, since
-    interconnecting transport nodes will prioritize announces into the slower segments that are
-    actually requested by nodes on these.
-
-    This means that slow, low-capacity or low-resource segments **don't** need to have full network
-    knowledge, since paths can always be recursively resolved from other segments that do have
-    knowledge about them.
+    This means that slow, low-capacity or low-resource segments **don't** need to have full network knowledge, since paths can always be recursively resolved from other segments that do have knowledge about them.

 In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full end-to-end connectivity in about one minute, given there is enough bandwidth available to process the required amount of announces.

@@ -415,9 +407,7 @@ The *link* in Reticulum terminology should not be viewed as a direct node-to-nod
    that is used to encrypt the channel. Information can now be exchanged reliably and securely.

 .. note::
-
-    It’s important to note that this methodology ensures that the source of the request does not need to
-    reveal any identifying information about itself. **The link initiator remains completely anonymous**.
+    It’s important to note that this methodology ensures that the source of the request does not need to reveal any identifying information about itself. **The link initiator remains completely anonymous**.

 When using *links*, Reticulum will automatically verify all data sent over the link, and can also automate retransmissions if *Resources* are used.

@@ -544,11 +534,7 @@ The reference setup can be considered a relatively stable platform to develop on
    operating system.

 .. note::
-
-    To avoid confusion, it is very important to note, that the reference interface device **does not**
-    use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
-    need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to
-    get or make such a device is available on the `RNode Page <https://github.com/markqvist/rnode_firmware>`_.
+    To avoid confusion, it is very important to note, that the reference interface device **does not** use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to get or make such a device is available on the `RNode Page <https://github.com/markqvist/rnode_firmware>`_.

 With the current reference setup, it should be possible to get on a Reticulum network for around 100$ even if you have none of the hardware already, and need to purchase everything.

@@ -543,11 +543,7 @@ pipx<span class="w"> </span>install<span class="w"> </span>rns
 </div>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
-of words. Setting it will of course not break any system packages, but will simply
-allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
-cases lead to version conflicts, it does not generally pose any problems, especially
-not in the case of installing Reticulum.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.</p>
 </div>
 </section>
 <section id="macos">
@@ -578,11 +574,7 @@ pip3<span class="w"> </span>install<span class="w"> </span>rns<span class="w"> <
 <p>On OpenWRT systems with sufficient storage and memory, you can install Reticulum and related utilities using the <cite>opkg</cite> package manager and <cite>pip</cite>.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>At the time of releasing this manual, work is underway to create pre-built
-Reticulum packages for OpenWRT, with full configuration, service
-and <code class="docutils literal notranslate"><span class="pre">uci</span></code> integration. Please see the <a class="reference external" href="https://github.com/gretel/feed-reticulum">feed-reticulum</a>
-and <a class="reference external" href="https://github.com/gretel/reticulum-openwrt">reticulum-openwrt</a>
-repositories for more information.</p>
+<p>At the time of releasing this manual, work is underway to create pre-built Reticulum packages for OpenWRT, with full configuration, service and <code class="docutils literal notranslate"><span class="pre">uci</span></code> integration. Please see the <a class="reference external" href="https://github.com/gretel/feed-reticulum">feed-reticulum</a> and <a class="reference external" href="https://github.com/gretel/reticulum-openwrt">reticulum-openwrt</a> repositories for more information.</p>
 </div>
 <p>To install Reticulum on OpenWRT, first log into a command line session, and then use the following instructions:</p>
 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span>
@@ -453,9 +453,7 @@ indirectly, but must first be established through a <em>single</em> destination.
 <li><p>An Ed25519 signature of the above information, verifying authenticity</p></li>
 </ul>
 <p>With this information, any Reticulum node that receives it will be able to reconstruct an outgoing destination to securely communicate with that destination. You might have noticed that there is one piece of information lacking to reconstruct full knowledge of the announced destination, and that is the aspect names of the destination. These are intentionally left out to save bandwidth, since they will be implicit in almost all cases. The receiving application will already know them. If a destination name is not entirely implicit, information can be included in the application specific data part that will allow the receiver to infer the naming.</p>
-<p>It is important to note that announces will be forwarded throughout the network according to a
-certain pattern. This will be detailed in the section
-<a class="reference internal" href="#understanding-announce"><span class="std std-ref">The Announce Mechanism in Detail</span></a>.</p>
+<p>It is important to note that announces will be forwarded throughout the network according to a certain pattern. This will be detailed in the section <a class="reference internal" href="#understanding-announce"><span class="std std-ref">The Announce Mechanism in Detail</span></a>.</p>
 <p>In Reticulum, destinations are allowed to move around the network at will. This is very different from protocols such as IP, where an address is always expected to stay within the network segment it was assigned in. This limitation does not exist in Reticulum, and any destination is <em>completely portable</em> over the entire topography of the network, and <em>can even be moved to other Reticulum networks</em> than the one it was created in, and still become reachable. To update its reachability, a destination simply needs to send an announce on any networks it is part of. After a short while, it will be globally reachable in the network.</p>
 <p>Seeing how <em>single</em> destinations are always tied to a private/public key pair leads us to the next topic.</p>
 </section>
@@ -535,13 +533,8 @@ application specific data, it will replace the old announce.</div>
 <p>According to these rules, an announce will propagate throughout the network in a predictable way, and make the announced destination reachable in a short amount of time. Fast networks that have the capacity to process many announces can reach full convergence very quickly, even when constantly adding new destinations. Slower segments of such networks might take a bit longer to gain full knowledge about the wide and fast networks they are connected to, but can still do so over time, while prioritising full and quickly converging end-to-end connectivity for their local, slower segments.</p>
 <div class="admonition tip">
 <p class="admonition-title">Tip</p>
-<p>Even very slow networks, that simply don’t have the capacity to ever reach <em>full</em> convergence
-will generally still be able to reach <strong>any other destination on any connected segments</strong>, since
-interconnecting transport nodes will prioritize announces into the slower segments that are
-actually requested by nodes on these.</p>
-<p>This means that slow, low-capacity or low-resource segments <strong>don’t</strong> need to have full network
-knowledge, since paths can always be recursively resolved from other segments that do have
-knowledge about them.</p>
+<p>Even very slow networks, that simply don’t have the capacity to ever reach <em>full</em> convergence will generally still be able to reach <strong>any other destination on any connected segments</strong>, since interconnecting transport nodes will prioritize announces into the slower segments that are actually requested by nodes on these.</p>
+<p>This means that slow, low-capacity or low-resource segments <strong>don’t</strong> need to have full network knowledge, since paths can always be recursively resolved from other segments that do have knowledge about them.</p>
 </div>
 <p>In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full end-to-end connectivity in about one minute, given there is enough bandwidth available to process the required amount of announces.</p>
 </section>
@@ -702,8 +695,7 @@ that is used to encrypt the channel. Information can now be exchanged reliably a
 </ul>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>It’s important to note that this methodology ensures that the source of the request does not need to
-reveal any identifying information about itself. <strong>The link initiator remains completely anonymous</strong>.</p>
+<p>It’s important to note that this methodology ensures that the source of the request does not need to reveal any identifying information about itself. <strong>The link initiator remains completely anonymous</strong>.</p>
 </div>
 <p>When using <em>links</em>, Reticulum will automatically verify all data sent over the link, and can also automate retransmissions if <em>Resources</em> are used.</p>
 </section>
@@ -824,10 +816,7 @@ operating system.</p>
 </ul>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>To avoid confusion, it is very important to note, that the reference interface device <strong>does not</strong>
-use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
-need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to
-get or make such a device is available on the <a class="reference external" href="https://github.com/markqvist/rnode_firmware">RNode Page</a>.</p>
+<p>To avoid confusion, it is very important to note, that the reference interface device <strong>does not</strong> use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to get or make such a device is available on the <a class="reference external" href="https://github.com/markqvist/rnode_firmware">RNode Page</a>.</p>
 </div>
 <p>With the current reference setup, it should be possible to get on a Reticulum network for around 100$ even if you have none of the hardware already, and need to purchase everything.</p>
 <p>This reference setup is of course just a recommendation for getting started easily, and you should tailor it to your own specific needs, or whatever hardware you have available.</p>
@@ -345,11 +345,7 @@ pip install rns --break-system-packages
 ```

 #### NOTE
-The `--break-system-packages` directive is a somewhat misleading choice
-of words. Setting it will of course not break any system packages, but will simply
-allow installing `pip` packages user- and system-wide. While this *could* in rare
-cases lead to version conflicts, it does not generally pose any problems, especially
-not in the case of installing Reticulum.
+The `--break-system-packages` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing `pip` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.

 ### MacOS

@@ -384,11 +380,7 @@ Adjust Python version and shell init script location according to your system.
 On OpenWRT systems with sufficient storage and memory, you can install Reticulum and related utilities using the opkg package manager and pip.

 #### NOTE
-At the time of releasing this manual, work is underway to create pre-built
-Reticulum packages for OpenWRT, with full configuration, service
-and `uci` integration. Please see the [feed-reticulum](https://github.com/gretel/feed-reticulum)
-and [reticulum-openwrt](https://github.com/gretel/reticulum-openwrt)
-repositories for more information.
+At the time of releasing this manual, work is underway to create pre-built Reticulum packages for OpenWRT, with full configuration, service and `uci` integration. Please see the [feed-reticulum](https://github.com/gretel/feed-reticulum) and [reticulum-openwrt](https://github.com/gretel/reticulum-openwrt) repositories for more information.

 To install Reticulum on OpenWRT, first log into a command line session, and then use the following instructions:

@@ -177,9 +177,7 @@ As an example, an announce in a simple messenger application might contain the f

 With this information, any Reticulum node that receives it will be able to reconstruct an outgoing destination to securely communicate with that destination. You might have noticed that there is one piece of information lacking to reconstruct full knowledge of the announced destination, and that is the aspect names of the destination. These are intentionally left out to save bandwidth, since they will be implicit in almost all cases. The receiving application will already know them. If a destination name is not entirely implicit, information can be included in the application specific data part that will allow the receiver to infer the naming.

-It is important to note that announces will be forwarded throughout the network according to a
-certain pattern. This will be detailed in the section
-[The Announce Mechanism in Detail](#understanding-announce).
+It is important to note that announces will be forwarded throughout the network according to a certain pattern. This will be detailed in the section [The Announce Mechanism in Detail](#understanding-announce).

 In Reticulum, destinations are allowed to move around the network at will. This is very different from protocols such as IP, where an address is always expected to stay within the network segment it was assigned in. This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and still become reachable. To update its reachability, a destination simply needs to send an announce on any networks it is part of. After a short while, it will be globally reachable in the network.

@@ -373,8 +371,7 @@ The *link* in Reticulum terminology should not be viewed as a direct node-to-nod
  

 #### NOTE
-It’s important to note that this methodology ensures that the source of the request does not need to
-reveal any identifying information about itself. **The link initiator remains completely anonymous**.
+It’s important to note that this methodology ensures that the source of the request does not need to reveal any identifying information about itself. **The link initiator remains completely anonymous**.

 When using *links*, Reticulum will automatically verify all data sent over the link, and can also automate retransmissions if *Resources* are used.

@@ -486,10 +483,7 @@ The reference setup can be considered a relatively stable platform to develop on
    operating system.

 #### NOTE
-To avoid confusion, it is very important to note, that the reference interface device **does not**
-use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
-need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to
-get or make such a device is available on the [RNode Page](https://github.com/markqvist/rnode_firmware).
+To avoid confusion, it is very important to note, that the reference interface device **does not** use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to get or make such a device is available on the [RNode Page](https://github.com/markqvist/rnode_firmware).

 With the current reference setup, it should be possible to get on a Reticulum network for around 100$ even if you have none of the hardware already, and need to purchase everything.

@@ -188,9 +188,7 @@ As an example, an announce in a simple messenger application might contain the f

 With this information, any Reticulum node that receives it will be able to reconstruct an outgoing destination to securely communicate with that destination. You might have noticed that there is one piece of information lacking to reconstruct full knowledge of the announced destination, and that is the aspect names of the destination. These are intentionally left out to save bandwidth, since they will be implicit in almost all cases. The receiving application will already know them. If a destination name is not entirely implicit, information can be included in the application specific data part that will allow the receiver to infer the naming.

-It is important to note that announces will be forwarded throughout the network according to a
-certain pattern. This will be detailed in the section
-:ref:`The Announce Mechanism in Detail<understanding-announce>`.
+It is important to note that announces will be forwarded throughout the network according to a certain pattern. This will be detailed in the section :ref:`The Announce Mechanism in Detail<understanding-announce>`.

 In Reticulum, destinations are allowed to move around the network at will. This is very different from protocols such as IP, where an address is always expected to stay within the network segment it was assigned in. This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and still become reachable. To update its reachability, a destination simply needs to send an announce on any networks it is part of. After a short while, it will be globally reachable in the network.

@@ -281,15 +279,9 @@ Once an announce has reached a transport node in the network, any other node in
 According to these rules, an announce will propagate throughout the network in a predictable way, and make the announced destination reachable in a short amount of time. Fast networks that have the capacity to process many announces can reach full convergence very quickly, even when constantly adding new destinations. Slower segments of such networks might take a bit longer to gain full knowledge about the wide and fast networks they are connected to, but can still do so over time, while prioritising full and quickly converging end-to-end connectivity for their local, slower segments.

 .. tip::
+    Even very slow networks, that simply don't have the capacity to ever reach *full* convergence will generally still be able to reach **any other destination on any connected segments**, since interconnecting transport nodes will prioritize announces into the slower segments that are actually requested by nodes on these.

-    Even very slow networks, that simply don't have the capacity to ever reach *full* convergence
-    will generally still be able to reach **any other destination on any connected segments**, since
-    interconnecting transport nodes will prioritize announces into the slower segments that are
-    actually requested by nodes on these.
-
-    This means that slow, low-capacity or low-resource segments **don't** need to have full network
-    knowledge, since paths can always be recursively resolved from other segments that do have
-    knowledge about them.
+    This means that slow, low-capacity or low-resource segments **don't** need to have full network knowledge, since paths can always be recursively resolved from other segments that do have knowledge about them.

 In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full end-to-end connectivity in about one minute, given there is enough bandwidth available to process the required amount of announces.

@@ -415,9 +407,7 @@ The *link* in Reticulum terminology should not be viewed as a direct node-to-nod
    that is used to encrypt the channel. Information can now be exchanged reliably and securely.

 .. note::
-
-    It’s important to note that this methodology ensures that the source of the request does not need to
-    reveal any identifying information about itself. **The link initiator remains completely anonymous**.
+    It’s important to note that this methodology ensures that the source of the request does not need to reveal any identifying information about itself. **The link initiator remains completely anonymous**.

 When using *links*, Reticulum will automatically verify all data sent over the link, and can also automate retransmissions if *Resources* are used.

@@ -544,11 +534,7 @@ The reference setup can be considered a relatively stable platform to develop on
    operating system.

 .. note::
-
-    To avoid confusion, it is very important to note, that the reference interface device **does not**
-    use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
-    need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to
-    get or make such a device is available on the `RNode Page <https://github.com/markqvist/rnode_firmware>`_.
+    To avoid confusion, it is very important to note, that the reference interface device **does not** use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to get or make such a device is available on the `RNode Page <https://github.com/markqvist/rnode_firmware>`_.

 With the current reference setup, it should be possible to get on a Reticulum network for around 100$ even if you have none of the hardware already, and need to purchase everything.