init commit

doc/tumbler-s7.7

@@ -0,0 +1,55 @@
+.Dd September 24, 2026
+.Dt TUMBLER-S7 7
+.Os
+.Sh NAME
+.Nm tumbler-s7
+.Nd S7 Scheme interface to the tumbler primitive
+.Sh SYNOPSIS
+Bd -literal -offset indent
+(load "./build/lib/enfilade.so" (inlet 'init_func 'init_enfilade_s7))
+
+(tumbler-compare "1" "1.1")
+(tumbler-add "3" "2.16.3")
+(tumbler-subtract "1.4.3" "1.1.1")
+.Ed
+.Sh DESCRIPTION
+The module exposes the small C tumbler implementation to S7 without requiring
+a separate Scheme tumbler object type.  Tumblers cross the FFI as dotted
+unsigned-integer strings.
+.Sh FUNCTIONS
+.Bl -tag -width tumbler-subtract
+.It Fn tumbler-compare a b
+Returns a negative integer, zero, or a positive integer according to the
+whole-tumbler ordering of
+.Fa a
+and
+.Fa b .
+.It Fn tumbler-add position offset
+Returns a new tumbler string containing Xanadu tumbler addition.
+.It Fn tumbler-subtract a b
+Returns the generalized non-negative tumbler difference.
+.El
+.Sh EXAMPLES
+.Bd -literal
+(tumbler-compare "1" "1.1")
+; => -1
+
+(tumbler-add "3" "2.16.3")
+; => "5.16.3"
+
+(tumbler-add "25.6.46.93" "0.0.3.1.21")
+; => "25.6.49.1.21"
+
+(tumbler-subtract "1.4.3" "1.1.1")
+; => "0.3.3"
+.Ed
+.Sh ERRORS
+Malformed tumbler strings raise
+.Ql TumblerAddressException .
+Allocation failures raise
+.Ql memory-error .
+.Sh SEE ALSO
+.Xr tumbler 3 ,
+.Xr enfilade-s7 7
+.Sh REFERENCES
+.Lk https://sentido-labs.com/en/library/201904240732/Xanadu%20Hypertext%20Documents.html