> I had a lot of headache thinking about lists and list-like structures.
> The root of problems seems the fact that cons is both a list prepend and
> a mutable tuple constructor in scheme, and an uncontrolled mixing that
> entails. A dotted list isn't a proper list, but you might be OK to use
> certain list procedures (eg `list-set!`). Forbidding such operations on
> type level is the most sound approach but it's unclear if it's not too
> limiting.

Yes. IMHO this is a good example of why Scheme should not be pinned down
to one type system.

Racket has explored the interaction between statically and dynamically
typed code. It tends to be difficult and/or expensive to stop
idiosyncratic data crossing the boundary from dynamic to static. E.g.
detecting an improper list is O(n), and it gets worse with nesting.

https://srfi.schemers.org/srfi-1/srfi-1.html#TheProcedures gives the
types used by SRFI 1. list-ref is specified to take a clist ("A proper
or circular list"). This is unnecessarily restrictive, and not all
Scheme implementations adhere to this.

>  > But would it burden your work to have two sets of source files?
>
> It's hard to judge without having a sense of what the format would be,
> but probably not.

OK. I'll create two quick proof-of-concept repos under
https://github.com/schemedoc -- one for the types and one for the
documentation -- based on your current S-expression files. Let me know
whether you find the layout reasonable. If not, we can change it. Let's
try to find an approach where we can minimize duplication of effort.

I'll notify in this thread when I'm done. Should take a couple of days.