~duangle/scopes

Re: [PATCH] suggested documentation changes

Details
Message ID
<CALet5G09nb+qvapHSv5iQo46Xy7KAnu+JxpLksocZPMtD3Kr1w@mail.gmail.com>
DKIM signature
missing
Download raw message
(Note I've changed the second point slightly after our IRC discussion.)

Thanks for all the revisions. It's certainly an advantage having someone that
speaks English as first language look carefully at the docs.
In my opinion all the wording / spelling changes are good and can be merged as
is. The change to a more impersonal voice is also appropriate.

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.

- 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

- 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.

Westerbly (radgeRayden) Snaydley.
Reply to thread Export thread (mbox)