Add syntax and semantics documents to the repo about verona HOT 6 CLOSED

Generating a ToC is entirely possible with Jekyll, I just didn't (yet). I do it for my UoC web page.

from verona.

The new website (#363) implements this partially (explore & faq pages). It would be nice to have a WIP primer on the syntax and semantics of the existing implementation, and possibly examples from Paul's advent coding (https://github.com/plietar/verona-advent).

from verona.

The navbar contents are generated from a .yml file, so it's easy to add more things. It doesn't do responsive design things yet to turn into a hamburger for tiny screens, so will need a bit of tweaking if we add a lot of things.

from verona.

Once thing we could do quickly and cheaply is merge existing documents at the top level, so that we keep the number of top items constant.

Another thing is to use a more powerful document generator like many projects that use github.io do, so that we can have a proper table of contents on the side and a more friendly navigation bar that can hide on small screens.

from verona.

Two public-facing documents in flight: ABI [#341] and Strings [#295]. These can go on the website.

Two sets of internal documents on the internal representations: 1IR [#357] and 2IR [#367]. These will remain internal.

We're still missing a primer on the Verona side of things. There are still some syntax (and to lesser extent, semantics) being discussed, but we already have some strong candidates to document more openly.

from verona.

We have decided to write internal documents for now and later on collate the knowledge in them in a public tutorial.

The reasoning is simple: the language is still under development and both syntax and semantics can still change. If we start writing public documents, we'll have to back-track and that's confusing. So, all internal documents for now have a warning that they're liable to change at any time.

However, those were written and validated by all of us after extensive meetings and PR discussions, so they're likely very close to the final semantics.

We also wrote it in a way that states what has been agreed already, not what's under discussion. So if there are things missing, it's because we haven't formed consensus yes.

This is the internal documentation directory: https://github.com/microsoft/verona/tree/master/docs/internal

These are the remaining PRs: #462, #465, #466, #467.

After those are merged we can close this issue. Every new semantics agreed upon will end up in the documents and we don't need to track them here.

from verona.