Re: [PATCH] suggested documentation changes

Message ID
DKIM signature
Download raw message
> 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.

> - On line 357: I think this addition makes the example too long for something that simple, maybe we can just consolidate this point with the previous example somehow.

In retrospect, I agree; I've changed the previous example slightly and
I hope this is more acceptable now.

Shawn Walker-Salas
Reply to thread Export thread (mbox)