Greetings,

Attached is a .patch that makes the following changes:

* drop number sections in menu due to readthedocs theme incompatibility
* fix some missing docstrings
* add missing docs for some Scopes modules
* various wording and formatting docstring fixes

Feedback welcome!

-- 
Shawn Walker-Salas

Greetings,

I've finally finished converting Scopes' documentation to markdown
(mkdocs) format.  I managed to get syntax highlighting working using
the existing scopeslexer after updating it (trivially) to Python 3.

Because of the size of the changes, I've chosen to instead supply the
"patches" via a fork of the Scopes repo on hg.sr.ht:

https://hg.sr.ht/~binarycrusader/scopes-md/log

You will want these changesets in this order:

https://hg.sr.ht/~binarycrusader/scopes-md/rev/066781654776397011580f4eae9035dbb66cb8fc

On Sat, 4 Jul 2020 at 12:49, Westerbly Snaydley <westerbly@gmail.com> wrote:
> On Sat, Jul 4, 2020 at 12:34, Shawn Walker <binarycrusader@gmail.com>
> wrote:
> > I guess I’m spoiled by the rust compiler’s reasoning about
> > lifetimes.  If I try to use ‘x’ once the binding has expired it
> > won’t let me and tells me why.  Here it seems like Scopes should
> > know the lifetime of the storage and then could prevent or warn about
> > further use.
>
> Scopes' borrow checker is opt-in, and the core is designed such that
> lower level constructs / APIs are not checked. The higher level APIs on

So if I'm guessing correctly, the borrow checker you're referring to
is the "view propagation" mechanism?  However, that can't be used with

On Sat, 4 Jul 2020 at 13:06, Westerbly Snaydley <westerbly@gmail.com> wrote:
> On Sat, Jul 4, 2020 at 14:48, Westerbly Snaydley <westerbly@gmail.com>
> wrote:
> > On Sat, Jul 4, 2020 at 12:34, Shawn Walker <binarycrusader@gmail.com>
> > wrote:
> >> I guess I’m spoiled by the rust compiler’s reasoning about
> >>  lifetimes.  If I try to use ‘x’ once the binding has expired it
> >>  won’t let me and tells me why.  Here it seems like Scopes should
> >>  know the lifetime of the storage and then could prevent or warn
> >> about  further use.
> >
> > Scopes' borrow checker is opt-in, and the core is designed such that
> > lower level constructs / APIs are not checked. The higher level APIs
> > on the other hand are built on top of those but with security added

[resending reply for list]

After sleep this is obvious in retrospect. Sorry for the noise.  The
missing piece was that I didn’t think of what scope the repl was
evaluating statements.

I had copied this from one of the tests and so was puzzled because I
hadn’t thought hard enough about scopes and the repl.

However, this does point out a possible nice usability enhancement for
the repl at least but maybe also the Scopes compiler?

I guess I’m spoiled by the rust compiler’s reasoning about lifetimes.
If I try to use ‘x’ once the binding has expired it won’t let me and

MINGW64 /g/Devel/scopes-repo/bin
$ ./scopes
  \\\
   \\\   Scopes 0.16 (Jul  3 2020, 22:39:29)
 ///\\\  http://scopes.rocks
///  \\\
$0 ► local y = 5
5
$0 ► let x = (alloca-array i32 y)
$imexebel:(mutable@ (storage = 'Function) i32)
$0 ► x @ 0 = 1
$0 ► x @ 1 = x @ 0 + 1
$0 ► x @ 2 = x @ 1 + 1
$0 ► x @ 3 = x @ 2 + 1

Attached are some suggested documentation changes for Scopes'
dataformat document.

This completes my initial pass over all of the documentation for Scopes.

Happy to change this as needed.

Thanks,
-- 
Shawn Walker-Salas

> I have a few notes on the changes to tutorial.rst (lines refer to the revised document):

> - On line 43, the warning is not exactly correct. To my knowledge (ie. on my machine) the scopes REPL does work as expected inside MSYS2/MinGW, however I use it from windows terminal as opposed to the stock emulator (mintty) that's bundled with the distribution. Also note we use "relative" color escape sequences to color output, meaning if some elements are not visible it's probably due to terminal misconfiguration. I would change the warning to be about avoiding mintty specifically (for the time being) instead of the shells. After all, it's very convenient to launch from mingw to make use of C libraries.

Yes, I've reworded this significantly in an attempt to make it clear
that the real issue is that the default terminal implementation in use
by the msys2 shell shortcuts (Mintty); if the -defterm or -conemu
options are used there's no problem.

> - On line 291, I can see how the note merits more attention, but the way it's written makes more sense in the storytelling format of "what we added" than a more removed warning. In general it would be good for us to develop a (verbal and visual) style to present these "gotchas"; the way the love2d wiki does it is particularly good: https://love2d.org/wiki/love.image.newImageData

I just moved the existing wording into a note.  However, I've
completely reworked this in a way that I think better reflects what
this section of the text is attempting to communicate.