Some example where the documentation is incomplete:
If you read the section on constant latches in the tutorial, it hints at the mechanics, but stops short of really explaining how they work under the hood and it doesn't really answer the question in that comment.
There seem to be a few places where the tutorial touches on a concept, but stops short of a proper deep explanation (its a tutorial, after all, not a deep technical analysis of the language).
Other areas that were never explained in detail is how the runtime should schedule streams. The compiler (would have, if it ever got finished) compiled streams into blocks of code and it was the runtimes job to schedule them to run when they become unblocked (the streams and latches they depend on receive data), but the mechanics of this - how it determines which order runnable tasks are to run in (remember, Adrian wanted ANI to be deadlock-proof) - was never explained.
Memory management was another one that was only touched on here on the mailing list. How is dynamic memory provided to a program? How does the garbage collector work, if there is one (I believe Adrian said he didn't want garbage collection and think he wanted linear types instead - I personally agree with that idea). Are values immutable?
To build real life programs, you need lots of powerful data structures and abstractions. The tutorial introduced a binary tree, but I feel there isn't enough documentation there to really show the mechanics of non-stream data structures or how to build them. For example, using the information we have available, how would you go about building a hash table?
Basically, all we have two small example programs (dining philosophers and the clock calculator), a tutorial that touches on the concepts behind ANI, but doesn't really delve into any deep details (and seems to be incomplete at that), an incomplete introduction to how the runtime was to function and an FAQ that only barely touches on technical details.
We're missing more detail on.. everything, we're missing a complete listing and/or reference of builtin/primitives, we're missing information on memory management and how to build data structures, we're missing (IMHO) sufficient details on how the runtime operates.
For this reason, I suggest that if we want to get an ANI-like language, we take the ideas and concepts provided here, but otherwise start from scratch. That way we can fill in the gaps in ways that makes sense to our language, rather than trying to patch together ANI's gaps in ways which we don't really know make sense as a whole because we don't know what research, work or tests Adrian went through to arrive at what we have now. Then when we have a complete spec, we implement an interpreter - forget about compiling (JIT or AOT), forget about faster than C, keep parallelism in mind, but not required for version one. The sooner there is a working interpreter, the sooner people can explore the language and the ideas and write real code (which will lead to more example code, something we are sorely lacking in the current version of ANI).
Finally, if we were to do that, we would need to change the language somewhat anyway to fill the gaps, so I suggest that the syntax is also revised to eliminate the bits that people seem to see as pain points. I understand the reasoning behind Adrian's decisions, but I don't think we need to or should stick to it exactly, lets not alienate people too much. The two main issues I would personally like reworked is the \ (I personally don't mind it, but its something a LOT of people complain about, so lets change it) and the fact that most of the language flows left to right, yet some flows right to left. Lets stay consistent and make everything left to right.
Example:
index = [int\\] <- {0,1,2,3,4,5,6,7,8,9};
\\index ("Hello, World #" + .. + "!\n") ->std.out;
Line one is right to left, line two is left to right.
But if we are changing these things anyway, lets at least look into the possibility of basing the syntax off something like Python or Ruby. We don't have to go that route, but lets not dismiss it right away without exploring it first. If the language were made at least a little bit more familiar (and less like Perl line-noise code golf... I know the semantics are different from other languages and that's why Adrian wanted to keep the syntax very different, but I think a middle ground exists) then I think it will be easier to get more people interested than if it looks like APL.
So.. what do you think? Shall we take a stab at this or does my idea not make much sense?
Regards,
Dan.