Various small documentation notices

diff --git a/README b/README
index db1e42f1388e07147f8b78c845e3aa3a458395bc0d51fafe209ece62214d9fce..71ead09073fe1d56f3b1da766bdd1a5fa7be6b3fa60c93d1542bef3512188ba6 100644 (file)
--- a/README
+++ b/README
@@ -2,3 +2,13 @@ KEKS is compact, deterministic, concise and streaming binary
 serialisation format. It is aimed to be lightweight in terms of CPU,
 memory, storage and codec implementation size usage. It supports wide
 range of data types, making it able to transparently replace JSON.
+KEKS/Schema is a schema definition format for describing data structures
+validation steps.
+KEKS/CM is a set of schemas and formats related to cryptographic tasks
+like signing, hashing and encryption.
+
+This repository contains implementations of KEKS codec on C99, Go,
+Python3 and Tcl (only encoder) languages. Implementation of KEKS/Schema
+on Tcl. Implementations of KEKS/CM and related utilities on C and Go.
+
+Home page: http://www.keks.cypherpunks.su/

diff --git a/c/README b/c/README
index 78f8a0aaa241c2e71992cbe57a4a56262e0e025b1b7a90da6662cfe2d8ddf850..714fc3fd38fe187f9fc55ad531f6aefd3558a79edc51d03758c9630d5b710478 100644 (file)
--- a/c/README
+++ b/c/README
@@ -1,2 +1,2 @@
-ckeks is C99 implementation of the KEKS codec.
-Look at doc/ for more information.
+CKEKS is C99 implementation of the KEKS codec, KEKS/Schema validator and
+part of KEKS/CM. Look at doc/ for more information.

diff --git a/c/cmd/pub-verify/pub-verify.c b/c/cmd/pub-verify/pub-verify.c
index ba459b7d9167dd9e5e6040cf293c05b6403b71736c60788aa2e0cb6bf794a983..3041e122bf682309f03e3d2afae7101138416c1ed20784373edb62f30051e621 100644 (file)
--- a/c/cmd/pub-verify/pub-verify.c
+++ b/c/cmd/pub-verify/pub-verify.c
@@ -1,4 +1,4 @@
-// ckeks -- C KEKS encoder implementation
+// CKEKS -- C99 KEKS encoder implementation
 // Copyright (C) 2024-2025 Sergey Matveev <stargrave@stargrave.org>
 //
 // This program is free software: you can redistribute it and/or modify

diff --git a/c/doc/index.texi b/c/doc/index.texi
index bfd22a63445d40fa63775e3b4d11d31cefa1914aab6e21f40893ada104703716..1f6cbf7bf19372378226e053768b09443156966f4443360932b70bf02345c96c 100644 (file)
--- a/c/doc/index.texi
+++ b/c/doc/index.texi
@@ -1,12 +1,12 @@
 \input texinfo
-@settitle ckeks
+@settitle CKEKS
 
 @copying
 Copyright @copyright{} 2024-2025 @email{stargrave@@stargrave.org, Sergey Matveev}
 @end copying
 
 @node Top
-@top ckeks
+@top CKEKS
 
 C99 implementation of the @url{http://www.keks.cypherpunks.su, KEKS}
 codec.
@@ -18,7 +18,7 @@ codec.
 @item No TAI64NA support.
 @end itemize
 
-ckeks is
+CKEKS is
 @url{https://www.gnu.org/philosophy/pragmatic.html, copylefted}
 @url{https://www.gnu.org/philosophy/free-sw.html, free software}
 licenced under @url{https://www.gnu.org/licenses/lgpl-3.0.html, GNU LGPLv3}.

diff --git a/c/lib/dec.c b/c/lib/dec.c
index f5048dff09f2cf9f2249c324cec8fe13f4ef3f9d102f56a76463407514c20bd5..2bd57773ea423804ce1ca54fde3587e10e45a2f06e077e6ad20f8f40e834b71a 100644 (file)
--- a/c/lib/dec.c
+++ b/c/lib/dec.c
@@ -1,4 +1,4 @@
-// ckeks -- C KEKS encoder implementation
+// CKEKS -- C99 KEKS encoder implementation
 // Copyright (C) 2024-2025 Sergey Matveev <stargrave@stargrave.org>
 //
 // This program is free software: you can redistribute it and/or modify

diff --git a/c/lib/dectai.c b/c/lib/dectai.c
index ace0cab89cb780a0b27afcd20c43178202526867afdf3f62f3cab366bae3da5a..ee56554cb10732f546e25b1828b90b35da35645b3cebbe2a4c38c761d0528fda 100644 (file)
--- a/c/lib/dectai.c
+++ b/c/lib/dectai.c
@@ -1,4 +1,4 @@
-// ckeks -- C KEKS encoder implementation
+// CKEKS -- C99 KEKS encoder implementation
 // Copyright (C) 2024-2025 Sergey Matveev <stargrave@stargrave.org>
 //
 // This program is free software: you can redistribute it and/or modify

diff --git a/c/lib/enc.c b/c/lib/enc.c
index a3b2e7497a2d35dae7d9f5343c14139a58e10ffebc59f8394aec5a584e33779f..22e286615572c5e4159fcebb423f13bf8d3f7b27df0054dfd54a5960d2a7b42c 100644 (file)
--- a/c/lib/enc.c
+++ b/c/lib/enc.c
@@ -1,4 +1,4 @@
-// ckeks -- C KEKS encoder implementation
+// CKEKS -- C99 KEKS encoder implementation
 // Copyright (C) 2024-2025 Sergey Matveev <stargrave@stargrave.org>
 //
 // This program is free software: you can redistribute it and/or modify

diff --git a/c/lib/enctai.c b/c/lib/enctai.c
index 414c9766ea7b78d8774e66cffde68739288dd5d58d64668cbaf381f73eb9045e..50a08d088ac002d469631a14aa98d4870e9cffa22a38320c389aed535b0a054d 100644 (file)
--- a/c/lib/enctai.c
+++ b/c/lib/enctai.c
@@ -1,4 +1,4 @@
-// ckeks -- C KEKS encoder implementation
+// CKEKS -- C99 KEKS encoder implementation
 // Copyright (C) 2024-2025 Sergey Matveev <stargrave@stargrave.org>
 //
 // This program is free software: you can redistribute it and/or modify

diff --git a/c/lib/items.c b/c/lib/items.c
index e742ab43ca9c901f58dfd9ce8e16cbecdb496224ed48302134e6ec2230838179..7d18f95d5c8c04b9b0562776a775c480bcbbb27ddc926f9ddc592b511d9b63d0 100644 (file)
--- a/c/lib/items.c
+++ b/c/lib/items.c
@@ -1,4 +1,4 @@
-// ckeks -- C KEKS encoder implementation
+// CKEKS -- C99 KEKS encoder implementation
 // Copyright (C) 2024-2025 Sergey Matveev <stargrave@stargrave.org>
 //
 // This program is free software: you can redistribute it and/or modify

diff --git a/c/lib/schema.c b/c/lib/schema.c
index 08cad23d14a661b3a3bff6830e1b03cbaaffd97a5f3c9d23a4b43f6d411c1097..259788240a456597c17212789a13bfa3a8b52391373b3167d1b66257b6f6b48d 100644 (file)
--- a/c/lib/schema.c
+++ b/c/lib/schema.c
@@ -1,4 +1,4 @@
-// ckeks -- C KEKS encoder implementation
+// CKEKS -- C99 KEKS encoder implementation
 // Copyright (C) 2024-2025 Sergey Matveev <stargrave@stargrave.org>
 //
 // This program is free software: you can redistribute it and/or modify

diff --git a/go/README b/go/README
index 3a850476465b77e91027d438198a555490a83191db039370e2f3143bbf557705..43f46e611e9efb5269d0ba5919d50f94bd02ee7b125fd8b1dacfed1845143f13 100644 (file)
--- a/go/README
+++ b/go/README
@@ -1,4 +1,5 @@
-GoKEKS is Go implementation of the KEKS codec.
+GoKEKS is Go implementation of the KEKS codec, KEKS/Schema validator and
+KEKS/CM.
 
 No FLOAT* support. They are stored/decoded just as a raw value.
 

diff --git a/spec/THANKS b/spec/THANKS
deleted file mode 100644 (file)
index ddad4e1..0000000
--- a/spec/THANKS
+++ /dev/null
@@ -1 +0,0 @@
-* Sergey Mayorov for his valuable consultation and suggestions

diff --git a/spec/cm/index.texi b/spec/cm/index.texi
index 12fa73ee20c418b78d381156fc850f935073ca96ed1cc011d3591602fb5bc98b..424099af2285db54cf48e6fab4b8d0a61df33ec0fc52c939d7392dd3fac04992 100644 (file)
--- a/spec/cm/index.texi
+++ b/spec/cm/index.texi
@@ -5,7 +5,7 @@
 @unnumbered Cryptographic messages
 
 Here are some suggested formats for use with cryptographic messages.
-They are written in @ref{TclSchemas, Tcl schemas} format.
+They are written in @ref{SchemaTcl, KEKS/Schema} format.
 
 @include cm/prv.texi
 @include cm/signed.texi

diff --git a/spec/comparison.texi b/spec/comparison.texi
new file mode 100644 (file)
index 0000000..ec18816
--- /dev/null
+++ b/spec/comparison.texi
@@ -0,0 +1,73 @@
+Are not there any satisfiable codecs?
+
+@multitable @columnfractions .30 .05 .05 .05 .05 .05
+
+@headitem @tab Schemaless @tab Simple @tab Deterministic @tab Streamable @tab Compact
+
+@item ASN.1 @url{https://en.wikipedia.org/wiki/Distinguished_Encoding_Rules#DER_encoding, DER} @tab
+    N @tab @strong{N} @tab Y @tab N @tab N
+@item ASN.1 @url{https://en.wikipedia.org/wiki/Distinguished_Encoding_Rules#CER_encoding, CER} @tab
+    N @tab @strong{N} @tab Y @tab Y @tab N
+@item @url{https://datatracker.ietf.org/doc/html/rfc1014, XDR} @tab
+    N @tab Y @tab N @tab N @tab N
+@item @url{https://www.JSON.org/json-en.html, JSON} @tab
+    Y @tab N @tab N @tab Y @tab N
+@item @url{https://bsonspec.org/, BSON} @tab
+    Y @tab Y @tab N @tab N @tab N
+@item @url{https://msgpack.org/, MessagePack} @tab
+    Y @tab Y @tab N @tab N @tab Y
+@item @url{https://datatracker.ietf.org/doc/html/rfc8949, CBOR} @tab
+    Y @tab N @tab N @tab Y @tab Y
+@item @url{https://datatracker.ietf.org/doc/html/draft-mcnally-deterministic-cbor-11, dCBOR} @tab
+    Y @tab @strong{N} @tab Y @tab N @tab Y
+@item @url{http://cr.yp.to/proto/netstrings.txt, Netstrings} @tab
+    Y @tab Y @tab Y @tab N @tab ~
+@item @url{https://wiki.theory.org/BitTorrentSpecification#Bencoding, Bencode} @tab
+    Y @tab Y @tab Y @tab Y @tab ~
+@item @url{https://en.wikipedia.org/wiki/Canonical_S-expressions, Canonical S-expression} @tab
+    Y @tab Y @tab Y @tab Y @tab ~
+@item KEKS @tab
+    Y @tab Y @tab Y @tab Y @tab Y
+
+@end multitable
+
+@multitable @columnfractions .20 .05 .05 .05 .05 .05 .05 .05 .05
+
+@headitem @tab Big str @tab Bin str @tab Human str @tab Ints @tab Bigints @tab Lists @tab Structures @tab Datetime
+
+@item ASN.1 DER @tab
+    Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y
+@item ASN.1 CER @tab
+    Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y
+@item XDR @tab
+    N @tab Y @tab Y @tab Y @tab N @tab Y @tab Y @tab N
+@item JSON @tab
+    Y @tab N @tab Y @tab Y @tab Y @tab Y @tab Y @tab N
+@item BSON @tab
+    N @tab Y @tab Y @tab Y @tab N @tab Y @tab Y @tab Y
+@item MessagePack @tab
+    N @tab Y @tab Y @tab Y @tab N @tab Y @tab Y @tab N
+@item CBOR @tab
+    Y @tab Y @tab Y @tab Y @tab N @tab Y @tab Y @tab N
+@item dCBOR @tab
+    Y @tab Y @tab Y @tab Y @tab N @tab Y @tab Y @tab N
+@item Netstrings @tab
+    Y @tab Y @tab N @tab N @tab N @tab N @tab N @tab N
+@item Bencode @tab
+    Y @tab Y @tab N @tab Y @tab Y @tab Y @tab Y @tab N
+@item CSExp @tab
+    Y @tab Y @tab N @tab N @tab N @tab Y @tab N @tab N
+@item KEKS @tab
+    Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y
+
+@end multitable
+
+Note about CBOR:
+
+@itemize
+@item Hardly you will find wide range of CBOR libraries supporting
+strict validation of deterministically encoded CBOR structures.
+@item Tagged string/integer can not be taken as a viable first-class
+bigint/datetime data support, because many decoders do not support tags
+and won't be able to interpret/validate them.
+@end itemize

diff --git a/spec/index.texi b/spec/index.texi
index 6441412e97605561cab40aa2dc2df3c7a615fd2b138d24849b5567bad06d227d..e7ccd42f8fe5102070c1a8af90a1ab6d3eb9f8e39145c2ab0b98b8a69a5a146f 100644 (file)
--- a/spec/index.texi
+++ b/spec/index.texi
@@ -52,79 +52,7 @@ It @strong{should} be frugal to CPU usage for both performance/memory
 constrained and high data volume applications.
 @end itemize
 
-Are not there any satisfiable codecs?
-
-@multitable @columnfractions .30 .05 .05 .05 .05 .05
-
-@headitem @tab Schemaless @tab Simple @tab Deterministic @tab Streamable @tab Compact
-
-@item ASN.1 @url{https://en.wikipedia.org/wiki/Distinguished_Encoding_Rules#DER_encoding, DER} @tab
-    N @tab @strong{N} @tab Y @tab N @tab N
-@item ASN.1 @url{https://en.wikipedia.org/wiki/Distinguished_Encoding_Rules#CER_encoding, CER} @tab
-    N @tab @strong{N} @tab Y @tab Y @tab N
-@item @url{https://datatracker.ietf.org/doc/html/rfc1014, XDR} @tab
-    N @tab Y @tab N @tab N @tab N
-@item @url{https://www.JSON.org/json-en.html, JSON} @tab
-    Y @tab N @tab N @tab Y @tab N
-@item @url{https://bsonspec.org/, BSON} @tab
-    Y @tab Y @tab N @tab N @tab N
-@item @url{https://msgpack.org/, MessagePack} @tab
-    Y @tab Y @tab N @tab N @tab Y
-@item @url{https://datatracker.ietf.org/doc/html/rfc8949, CBOR} @tab
-    Y @tab N @tab N @tab Y @tab Y
-@item @url{https://datatracker.ietf.org/doc/html/draft-mcnally-deterministic-cbor-11, dCBOR} @tab
-    Y @tab @strong{N} @tab Y @tab N @tab Y
-@item @url{http://cr.yp.to/proto/netstrings.txt, Netstrings} @tab
-    Y @tab Y @tab Y @tab N @tab ~
-@item @url{https://wiki.theory.org/BitTorrentSpecification#Bencoding, Bencode} @tab
-    Y @tab Y @tab Y @tab Y @tab ~
-@item @url{https://en.wikipedia.org/wiki/Canonical_S-expressions, Canonical S-expression} @tab
-    Y @tab Y @tab Y @tab Y @tab ~
-@item KEKS @tab
-    Y @tab Y @tab Y @tab Y @tab Y
-
-@end multitable
-
-@multitable @columnfractions .20 .05 .05 .05 .05 .05 .05 .05 .05
-
-@headitem @tab Big str @tab Bin str @tab Human str @tab Ints @tab Bigints @tab Lists @tab Structures @tab Datetime
-
-@item ASN.1 DER @tab
-    Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y
-@item ASN.1 CER @tab
-    Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y
-@item XDR @tab
-    N @tab Y @tab Y @tab Y @tab N @tab Y @tab Y @tab N
-@item JSON @tab
-    Y @tab N @tab Y @tab Y @tab Y @tab Y @tab Y @tab N
-@item BSON @tab
-    N @tab Y @tab Y @tab Y @tab N @tab Y @tab Y @tab Y
-@item MessagePack @tab
-    N @tab Y @tab Y @tab Y @tab N @tab Y @tab Y @tab N
-@item CBOR @tab
-    Y @tab Y @tab Y @tab Y @tab N @tab Y @tab Y @tab N
-@item dCBOR @tab
-    Y @tab Y @tab Y @tab Y @tab N @tab Y @tab Y @tab N
-@item Netstrings @tab
-    Y @tab Y @tab N @tab N @tab N @tab N @tab N @tab N
-@item Bencode @tab
-    Y @tab Y @tab N @tab Y @tab Y @tab Y @tab Y @tab N
-@item CSExp @tab
-    Y @tab Y @tab N @tab N @tab N @tab Y @tab N @tab N
-@item KEKS @tab
-    Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y @tab Y
-
-@end multitable
-
-Note about CBOR:
-
-@itemize
-@item Hardly you will find wide range of CBOR libraries supporting
-strict validation of deterministically encoded CBOR structures.
-@item Tagged string/integer can not be taken as a viable first-class
-bigint/datetime data support, because many decoders do not support tags
-and won't be able to interpret/validate them.
-@end itemize
+@include comparison.texi
 
 @insertcopying
 
@@ -133,6 +61,7 @@ and won't be able to interpret/validate them.
 @include encoding/index.texi
 @include schema/index.texi
 @include cm/index.texi
+@include thanks.texi
 
 @node Concepts Index
 @unnumbered Concepts Index

diff --git a/spec/schema/index.texi b/spec/schema/index.texi
index 227a434d71e39fd4237aceb26d706a514b85e973b65c0d103d7b3af05fcf96d5..3f515f822ae05defa6b03af26700dfb5c1b33259cacffbef113191e188420036 100644 (file)
--- a/spec/schema/index.texi
+++ b/spec/schema/index.texi
@@ -1,9 +1,9 @@
-@node Schemas
-@cindex Schemas
+@node Schema
+@cindex schema
 @cindex structure validation
-@cindex data schemas
+@cindex data schema
 @nodedescription Structure validation against schemas
-@unnumbered Data schemas
+@unnumbered Schemas
 
 Although KEKS can be decoded without any schema definition/specification,
 data structures are likely to be checked against some kind of the schema.

diff --git a/spec/schema/tcl.texi b/spec/schema/tcl.texi
index a00363cb5e9e14617859cf3677670d8cc413e81892a1f18c76fb4405691afa75..758e6b55cc9ed5676955aad979797de545f581a3a2fd1cd294ec98e056bd6922 100644 (file)
--- a/spec/schema/tcl.texi
+++ b/spec/schema/tcl.texi
@@ -1,12 +1,14 @@
-@node TclSchemas
-@cindex Tcl schemas
+@node SchemaTcl
+@cindex Tcl schema
+@cindex KEKS/Schema
 @nodedescription Tcl-written schemas
-@section Tcl schemas
+@section Tcl schema
 
 Validation commands are pretty low-level and are inconvenient to write
 by hand, at least because of huge quantity of TAKEs.
 @command{tcl/schema-marshal} utility gives ability to convert much more
-nicer schemas written on Tcl language to the KEKS-encoded commands.
+nicer schemas written on Tcl language to the KEKS-encoded commands. We
+call that Tcl-written schemas KEKS/Schema.
 
 Example with "our" structure can be written as:
 
@@ -51,7 +53,7 @@ specify empty list of types in second argument.
 @code{>n} and @code{<n} arguments allow checking of the integer value or
 the lengths. @code{>0} assures that either list/map or strings are not
 empty. @code{len=n} checks the exact length. @code{=v} checks that given
-element has specified value.
+element has specified string/binary value (use @code{len=} for integers).
 
 @code{prec=p} issues TIMEPREC command, but instead of specifying the raw
 integer values, you choose one of: s, ms, us, ns, ps, fs, as. @code{utc}
@@ -60,3 +62,7 @@ issues UTC command.
 @code{of s} argument issues checking of EACH element of the list or map
 against the specified schema, or against specified type if @code{s} is a
 known type.
+
+@code{schema-include filename.tcl} command used instead of @code{field}
+allows inclusion of the specified file with the path relative to given
+schema file.

diff --git a/spec/thanks.texi b/spec/thanks.texi
new file mode 100644 (file)
index 0000000..3184088
--- /dev/null
+++ b/spec/thanks.texi
@@ -0,0 +1,11 @@
+@node Thanks
+@cindex thanks
+@unnumbered Thanks
+
+@itemize
+
+@item Sergey Mayorov for his valuable consultation and suggestions.
+@item Anton Rudenko for the initial unittests of the Python and Go codec
+    implementation.
+
+@end itemize