Homogenize markup used for section headings
Plus other minor cleanups
Change-Id: I356642e8d4c379ffb1b70789cba24497a7f8f393
diff --git a/tlv.rst b/tlv.rst
index 240af02..35d4edb 100644
--- a/tlv.rst
+++ b/tlv.rst
@@ -1,5 +1,5 @@
Type-Length-Value (TLV) Encoding
---------------------------------
+================================
Each NDN packet is encoded in :abbr:`TLV (Type-Length-Value)` format.
NDN Interest and Data packets are distinguished by the type number in the first and outermost TLV\ :sub:`0`\ .
@@ -10,8 +10,9 @@
There is also no packet fragmentation support at network level.
Whenever needed, NDN packets may be fragmented and reassembled hop-by-hop\ [#f1]_.
+
Variable-Size Encoding for Type and Length
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------
.. note::
The text below and that in the :ref:`TLV` section are adapted from an earlier packet specification draft by Mark Stapp.
@@ -42,13 +43,14 @@
- If the first octet is 255 (``0xFF``), the number is encoded in the following 8 octets, in network byte-order.
This number must be greater than 4294967295 (``0xFFFFFFFF``).
-A number MUST be encoded in the shortest format.
+A number MUST be encoded using the shortest possible format.
For example, the number 1024 is encoded as ``%xFD0400`` in ``VAR-NUMBER-3`` format, not ``%xFE00000400`` in ``VAR-NUMBER-5`` format.
+
.. _TLV:
NDN TLV Encoding
-~~~~~~~~~~~~~~~~
+----------------
TLV encoding for NDN packets is defined as follows::
@@ -57,20 +59,21 @@
TLV-LENGTH = VAR-NUMBER-1 / VAR-NUMBER-3 / VAR-NUMBER-5 / VAR-NUMBER-9
TLV-VALUE = *OCTET
-TLV-TYPE MUST be in the range ``1-4294967295`` (inclusive).
-Zero is reserved to indicate an invalid TLV element and MUST NOT appear on the wire.
-TLV-TYPE SHOULD be unique at all nested levels.
-Section :ref:`types` of this document lists initial TLV-TYPE assignments.
+``TLV-TYPE`` MUST be in the range [1, 4294967295].
+Type 0 is reserved to indicate an invalid TLV element and MUST NOT appear on the wire.
+``TLV-TYPE`` SHOULD be unique at all nested levels.
+Section :ref:`types` of this document lists the initial ``TLV-TYPE`` assignments.
The ``TLV-LENGTH`` field indicates number of bytes that ``TLV-VALUE`` uses.
-It **does not** include number of bytes that ``TLV-TYPE`` and ``TLV-LENGTH`` fields themselves occupy.
-In particular, empty payload TLV will carry ``TLV-LENGTH`` equal to 0.
+It does not include the number of bytes that ``TLV-TYPE`` and ``TLV-LENGTH`` fields themselves occupy.
+In particular, a TLV element with empty value will have ``TLV-LENGTH`` equal to 0.
This encoding offers a reasonable balance between compactness and flexibility.
-Most common, standardized TLV-TYPE numbers will be allocated from a small-integer number-space, and these common types will be able to use the compact, single-byte encoding.
+Most common, standardized ``TLV-TYPE`` numbers will be allocated from a small-integer number-space, and these common types will be able to use the compact, single-byte encoding.
+
Non-Negative Integer Encoding
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
A number of TLV elements in the NDN packet format take a non-negative integer as their TLV-VALUE, with the following definition::
@@ -95,18 +98,19 @@
65535 => TT02FFFF
65536 => TT0400010000
+
.. _evolvability:
Considerations for Evolvability of TLV-Based Encoding
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------------
-To ensure that the TLV-based protocol can evolve over time without requiring flag days, the least significant bit of TLV-TYPE number (unless overridden by the specification of a particular network/library/application TLV element) is reserved to indicate whether that TLV element is "critical" or "non-critical".
+To ensure that the TLV-based protocol can evolve over time without requiring flag days, the least significant bit of ``TLV-TYPE`` (unless overridden by the specification of a particular network/library/application TLV element) is reserved to indicate whether that TLV element is *critical* or *non-critical*.
A compliant TLV format decoder should follow the order, quantity, and presence requirements of the recognized elements defined in the corresponding specification.
At the same time, if the decoder encounters an unrecognized or out-of-order element, the behavior should be as follows:
-- if the least significant bit of the element's TLV-TYPE number is ``1``, abort decoding and report an error;
-- if the least significant bit of the element's TLV-TYPE number is ``0``, ignore the element and continue decoding;
-- TLV-TYPE numbers 0-31 (inclusive) are "grandfathered" and are all designated as "critical" for the purposes of packet processing.
+- if the least significant bit of the element's ``TLV-TYPE`` number is 1, abort decoding and report an error;
+- if the least significant bit of the element's ``TLV-TYPE`` number is 0, ignore the element and continue decoding;
+- ``TLV-TYPE`` numbers in the range [0, 31] are "grandfathered" and are all designated as *critical* for the purposes of packet processing.
.. note::
A recognized element is considered out-of-order if it appears in the element order that violates a specification. For example:
@@ -114,6 +118,7 @@
- when a specification defines a sequence {``F1`` ``F2`` ``F3``}, an element ``F3`` would be out-of-order in the sequence {``F1`` ``F3`` ``F2``};
- for {``F1`` ``F2?`` ``F3``} specification (i.e., when ``F2`` is optional, ``F2`` would be out-of-order in the same sequence {``F1`` ``F3`` ``F2``}.
+
.. rubric:: Footnotes
.. [#f1] `"Packet Fragmentation in NDN: Why NDN Uses Hop-By-Hop Fragmentation (NDN Memo)" by A. Afanasyev, J. Shi, L. Wang, B. Zhang, and L. Zhang., NDN Memo, Technical Report NDN-0032 <https://named-data.net/publications/techreports/ndn-0032-1-ndn-memo-fragmentation/>`__