From: Sergey Matveev <stargrave@stargrave.org>
Date: Wed, 22 Jan 2025 14:56:40 +0000 (+0300)
Subject: Less @anchors
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=4256c2c3a72d2b3d81a3249f7151124721c1ae06bfe1adca2db08b44086f3062;p=keks.git

Less @anchors
---

diff --git a/spec/encoding/blob.texi b/spec/encoding/blob.texi
index f425931..302a5ea 100644
--- a/spec/encoding/blob.texi
+++ b/spec/encoding/blob.texi
@@ -1,5 +1,4 @@
 @node Blobs
-@anchor{BLOB}
 @cindex BLOB
 @cindex chunk
 @section Blobs
@@ -8,10 +7,10 @@ Blob (binary large object) allows you to transfer binary data in chunks,
 in a streaming way, when data may not fit in memory.
 
 64-bit big-endian integer follows the BLOB tag, setting the following
-chunks payload size (+1). Then come one or more @ref{BIN} strings with
-the chunk-length payload. All of them, except for the last one, must
-have fixed chunk length payload. Last terminating string's payload must
-be shorter.
+chunks payload size (+1). Then come one or more @ref{Strings, BIN}
+strings with the chunk-length payload. All of them, except for the last
+one, must have fixed chunk length payload. Last terminating string's
+payload must be shorter.
 
 Data format definition must specify exact chunk size expected to be
 used, if it needs deterministic encoding.
diff --git a/spec/encoding/index.texi b/spec/encoding/index.texi
index 987c423..2522627 100644
--- a/spec/encoding/index.texi
+++ b/spec/encoding/index.texi
@@ -11,14 +11,14 @@ Possible values for the tag:
 @multitable {dec} {hex} {12345678} {len} {float256}
 @headitem dec @tab hex @tab bin @tab vlen @tab description
 
-@item 000 @tab 00 @tab @code{00000000} @tab 0 @tab @ref{Containers, EOC}
+@item 000 @tab 00 @tab @code{00000000} @tab 0 @tab @ref{LIST, EOC}
 @item 001 @tab 01 @tab @code{00000001} @tab 0 @tab @ref{Primitives, NIL}
 @item 002 @tab 02 @tab @code{00000010} @tab 0 @tab @ref{Primitives, FALSE}
 @item 003 @tab 03 @tab @code{00000011} @tab 0 @tab @ref{Primitives, TRUE}
 @item 004 @tab 04 @tab @code{00000100} @tab 16 @tab @ref{UUID}
 @item [...]
-@item 008 @tab 08 @tab @code{00001000} @tab 0 @tab @ref{Containers, LIST}
-@item 009 @tab 09 @tab @code{00001001} @tab 0 @tab @ref{Containers, MAP}
+@item 008 @tab 08 @tab @code{00001000} @tab 0 @tab @ref{LIST}
+@item 009 @tab 09 @tab @code{00001001} @tab 0 @tab @ref{MAP}
 @item 010 @tab 0A @tab @code{00001010} @tab
 @item 011 @tab 0B @tab @code{00001011} @tab 8+~ @tab @ref{Blobs, BLOB}
 @item 012 @tab 0C @tab @code{00001100} @tab 1+~ @tab @ref{Integers, +INT}
@@ -60,5 +60,6 @@ Possible values for the tag:
 @include encoding/float.texi
 @include encoding/tai64.texi
 @include encoding/magic.texi
-@include encoding/cont.texi
+@include encoding/list.texi
+@include encoding/map.texi
 @include encoding/blob.texi
diff --git a/spec/encoding/list.texi b/spec/encoding/list.texi
new file mode 100644
index 0000000..4582a38
--- /dev/null
+++ b/spec/encoding/list.texi
@@ -0,0 +1,19 @@
+@node LIST
+@cindex EOC
+@section LIST
+
+LIST contains a concatenation of items of arbitrary type, terminated by
+EOC atom.
+
+@verbatim
+LIST [ITEM0 || ITEM1 || ...] EOC
+@end verbatim
+
+Example representations:
+
+@multitable @columnfractions .5 .5
+
+@item LIST[] @tab @code{08 00}
+@item LIST[INT(123) FALSE] @tab @code{08 0C817B 02 00}
+
+@end multitable
diff --git a/spec/encoding/cont.texi b/spec/encoding/map.texi
similarity index 63%
rename from spec/encoding/cont.texi
rename to spec/encoding/map.texi
index 0d3a8e8..ebfdf45 100644
--- a/spec/encoding/cont.texi
+++ b/spec/encoding/map.texi
@@ -1,21 +1,7 @@
-@node Containers
-@cindex containers
-@section Containers
-
-Containers do not have any explicit length, but are terminated by EOC
-(end of contents) tag.
-
-@anchor{LIST}
-@cindex LIST
-@cindex EOC
-LIST contains a concatenation of items of arbitrary type.
-
-@verbatim
-LIST [ITEM0 || ITEM1 || ...] EOC
-@end verbatim
-
-@anchor{MAP}
+@node MAP
 @cindex MAP
+@section MAP
+
 MAP contains concatenation of @ref{Strings, STR(key)}-value pairs. Keys
 @strong{must} be non-empty, unique and length-first bytewise ascending ordered.
 
@@ -34,9 +20,8 @@ Example representations:
 
 @multitable @columnfractions .5 .5
 
-@item LIST[] @tab @code{08 00}
-@item LIST[INT(123) FALSE] @tab @code{08 0C817B 02 00}
 @item MAP[foo: LIST["bar"]] @tab @code{09 C3666F6F 08 C3626172 00 00}
 @item SET[sig, dh] @tab @code{09 C26468 01 C3736967 01 00}
 
 @end multitable
+
diff --git a/spec/encoding/prim.texi b/spec/encoding/prim.texi
index aca3125..76c3ab0 100644
--- a/spec/encoding/prim.texi
+++ b/spec/encoding/prim.texi
@@ -1,5 +1,4 @@
 @node Primitives
-@anchor{NIL}
 @cindex NIL
 @cindex FALSE
 @cindex TRUE
diff --git a/spec/encoding/str.texi b/spec/encoding/str.texi
index ef84822..8f6607d 100644
--- a/spec/encoding/str.texi
+++ b/spec/encoding/str.texi
@@ -1,5 +1,4 @@
 @node Strings
-@anchor{BIN}
 @cindex BIN
 @cindex STR
 @section Strings
diff --git a/spec/encoding/table.texi b/spec/encoding/table.texi
index 754fac5..96aa26f 100644
--- a/spec/encoding/table.texi
+++ b/spec/encoding/table.texi
@@ -4,7 +4,7 @@
 @multitable {dec} {hex} {12345678} {len} {float256}
 @headitem dec @tab hex @tab bin @tab vlen @tab description
 
-@item 000 @tab 00 @tab @code{00000000} @tab 0 @tab @ref{Containers, EOC}
+@item 000 @tab 00 @tab @code{00000000} @tab 0 @tab @ref{LIST, EOC}
 @item 001 @tab 01 @tab @code{00000001} @tab 0 @tab @ref{Primitives, NIL}
 @item 002 @tab 02 @tab @code{00000010} @tab 0 @tab @ref{Primitives, FALSE}
 @item 003 @tab 03 @tab @code{00000011} @tab 0 @tab @ref{Primitives, TRUE}
@@ -12,8 +12,8 @@
 @item 005 @tab 05 @tab @code{00000101} @tab 0 @tab
 @item 006 @tab 06 @tab @code{00000110} @tab 0 @tab
 @item 007 @tab 07 @tab @code{00000111} @tab 0 @tab
-@item 008 @tab 08 @tab @code{00001000} @tab 0 @tab @ref{Containers, LIST}
-@item 009 @tab 09 @tab @code{00001001} @tab 0 @tab @ref{Containers, MAP}
+@item 008 @tab 08 @tab @code{00001000} @tab 0 @tab @ref{LIST}
+@item 009 @tab 09 @tab @code{00001001} @tab 0 @tab @ref{MAP}
 @item 010 @tab 0A @tab @code{00001010} @tab 0 @tab
 @item 011 @tab 0B @tab @code{00001011} @tab 8+~ @tab @ref{Blobs, BLOB}
 @item 012 @tab 0C @tab @code{00001100} @tab 1+~ @tab @ref{Integers, +INT}
diff --git a/spec/schema.texi b/spec/schema.texi
index 031e0c3..acd1ddf 100644
--- a/spec/schema.texi
+++ b/spec/schema.texi
@@ -8,10 +8,10 @@ readable language somewhere nearby.
 For being able to streamingly generate the serialised data, you have to
 worry about @ref{MAP}'s keys ordering. Remember that it is length-first one.
 
-By default binary data is expected to be encoded as @ref{BIN}. If you
-expect to deal with huge amounts of data, then probably you should use
-the @ref{BLOB} type. Generally you have to differentiate field names for
-ordinary strings and blobs.
+By default binary data is expected to be encoded as @ref{Strings, BIN}.
+If you expect to deal with huge amounts of data, then probably you
+should use the @ref{Blobs, BLOB} type. Generally you have to
+differentiate field names for ordinary strings and blobs.
 
 For relatively small structures it could be wise to use reasonably short
 key names. However it may be difficult and not obvious to keep the
@@ -32,4 +32,4 @@ guessing the context of the data inside.
 
 If you really desire more compact encoding, even agree to use schema
 definitions, then think about replacing MAPs with @ref{LIST}s. Non-present
-values can be indicated by @ref{NIL} tag.
+values can be indicated by @ref{Primitives, NIL} tag.