Translatable XML help screens

[djsrv]

This PR reworks help screens so that they can be more easily translated to other languages. Help screens are now written in human-readable (and writable!) XML and are rendered to PNGs by a new "Help translator" library. Documentation on the translation workflow and the XML format are in the help folder.

I think this is in a pullable state right now, but it's still missing a few help screens that are exceedingly complicated or require features I haven't yet implemented:

• addCustomBlock
• addVariable
• doFor
• doRun
• evaluateCustomBlock
• reportCombine

This falls back to the old help screens when the new ones aren't present, so that shouldn't be a major problem for the time being.

Due to the sheer number of help screens I had to rewrite in XML, there are probably some errors somewhere. So I need to proofread them all again, and they could probably use a few more eyes on them as well. :)

[djsrv]

I've switched to Linux and noticed some problems with this PR that occur outside of the Mac ecosystem, so I've pushed a few changes:

• Allow either Baskerville or Libre Baskerville, since Baskerville is only installed by default on Macs.
• Make sure that help screens are rendered at the same size on retina and non-retina screens.

I've also pushed numerous typo fixes, since I didn't notice my spell checker wasn't enabled for XML over the summer. Sorry about that. :/

Since I'm on break now, I also could break this into multiple PRs like @cycomachead suggested, if that would make this easier to pull. :)

For the future, I think something like this is probably most easily reviewed in steps. The first can be code with a couple examples, and then the next set of PRs can be each group of help screens.

[cycomachead]

That sounds great Dylan! 👍 from me.

…

-- Michael Ball From my iPhone michaelball.co

On Dec 21, 2019, at 2:29 PM, Dylan S ***@***.***> wrote:  I've switched to Linux and noticed some problems with this PR that occur outside of the Mac ecosystem, so I've pushed a few changes: Allow either Baskerville or Libre Baskerville, since Baskerville is only installed by default on Macs. Make sure that help screens are rendered at the same size on retina and non-retina screens. I've also pushed numerous typo fixes, since I didn't notice my spell checker wasn't enabled for XML over the summer. Sorry about that. :/ Since I'm on break now, I also could break this into multiple PRs like @cycomachead suggested, if that would make this easier to pull. :) For the future, I think something like this is probably most easily reviewed in steps. The first can be code with a couple examples, and then the next set of PRs can be each group of help screens. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[brianharvey]

I am reading through the help screens. My plan is to do all of that, leaving the actual code for Michael to review in parallel.

I've just started, and I have one minor complaint, which if you have time would be a better use of it imho than splitting up the PR. Look at doGotoObject.png. The first three options are equally spaced in the menu (of course), but the arrowheads of the annotations aren't. The second one should point a little higher. Even better, if it's easy, would be if the entire annotation group were centered, so the middle arrow would be horizontal and the others slightly angled.

I think probably we made a decision somewhere along the line to suppress small changes in angle of the arrows, but now I'm looking at this screen, it looks unprofessional.

Another alternative, to which I'm open, would be to reduce the font size of these annotations (not font size in general) so that all three arrows could be horizontal. (The arrowheads would also have to be smaller.)

Meanwhile I'll keep reading...

[djsrv]

Fixed on my local copy (including the centering request). I need to get up early, so I'll clean up the code and push tomorrow.

[brianharvey]

I just made a PR, but apparently it wasn't treated as a PR to this PR, but as a new one:

#2540

Here's the comment that went with it:

Most of these reflect recent changes in the actual blocks. There are three things I'd like Dylan to work on:

changePenHSVA_graph.png: This picture, used in several help screens, includes annotations as pixels. Could they be made translatable?

changeScale.png: descender of "g" cut off. I noticed it on this screen, but it's a general problem.

doSwitchToCostume.png: I added a script, and as a result, the previous row extends past the right edge of the frame. I thought maybe it was becasuse of retina, but when I disabled retina mode the same thing happened when I compiled the xml.

Thanks!

more changes coming...

[brianharvey]

More help screens edited -- only three palettes to go!

Below are the things I need Dylan to fix. Several of them are the same problem: scripts end up wider than the window, even if I turn off retina support, and even if I use the scale="0.8" thing.

reportGetSoundAttribute.png:
, more control over arrows
Also, titles have moved to below the heading block.

reportPenTrailsAsCostume.xml: Script comes out too wide when compiled.
Scale="0.6" doesn't affect it.

reportIfElse.png: Script too wide. And no zebra coloring!

fork.png: xml is correct, png is missing a letter in "draw"

evaluate.png: In the phrase "the input variable function" the word "function" should be in courier font. (More generally, it'd be nice to be able to put HTML tags for font, color, etc. inside text.) Oh, and up on top there's supposed to be an arrow between the two blocks. (There are a few more like this in other blocks.)

doTellTo.xml: The last script had the first (sprite) input to tell empty. I put in "Sprite(2)" as it should be, but when I compile it, the script is too wide.

reportAskFor.xml: I changed a word in the text, and when I compiled, all the scripts are too wide.

createClone.png: This time the help is too /tall/, so the bottom edge is clipped. (I didn't generate this picture; it came this way in the PR.)

[djsrv]

changePenHSVA_graph.png: This picture, used in several help screens, includes annotations as pixels. Could they be made translatable?

It would probably be best to turn this into an SVG. Will do.

changeScale.png: descender of "g" cut off. I noticed it on this screen, but it's a general problem.

This is a problem that Morphic has with Baskerville in general.

I'll investigate what's causing it, but I'm a bit scared to mess with something as integral as Snap!'s text rendering.

[Multiple problems with scripts being too large...]

Those blocks are definitely rendering bigger than they are on my computer(s). The obvious problem would be if you have a custom block zoom. Otherwise, I'm not sure...

Also, the scale attribute currently only works on scripts within a diagram tag, which is an oversight on my part. I'll fix that.

reportGetSoundAttribute.png
, more control over arrows

The changes I'm making for doGotoObject should allow that.

Also, titles have moved to below the heading block.
reportIfElse.png: Script too wide. And no zebra coloring!
fork.png: xml is correct, png is missing a letter in "draw"

These should all be easy fixes.

evaluate.png: In the phrase "the input variable function" the word "function" should be in courier font. (More generally, it'd be nice to be able to put HTML tags for font, color, etc. inside text.)

This is harder but shouldn't be too bad since I already made it so arbitrary morphs can be inlined.

Oh, and up on top there's supposed to be an arrow between the two blocks. (There are a few more like this in other blocks.)

This would actually be a huge pain to implement, for rather few screens. I'll try to figure out how to do it elegantly...

createClone.png: This time the help is too /tall/, so the bottom edge is clipped. (I didn't generate this picture; it came this way in the PR.)

Not seeing this on my end.

[djsrv]

I've pushed the changes for doGotoObject. You can mark an annotation with arrow-horizontal="true", which forces the annotation to be positioned so that its arrow is horizontal. Any annotations above are placed higher than they would normally be.

<annotations>
    <small-p>Move the sprite to...</small-p>
    <small-p>anywhere on the stage</small-p>
    <small-p arrow-horizontal="true">where the mouse is pointing</small-p>
    <small-p>the point (0, 0)</small-p>
    <small-p>another sprite's position</small-p>
</annotations>

[towerofnix]

This project looks super amazing!! :'o Here are a, um... a little more than a few nitpicks/mistakes/suggestions I had reviewing all of them.

• The help screen for "broadcast and wait" has info on how to use the dropdown, but "broadcast" doesn't also have it. Probably new users will check out the help for "broadcast" first, so should it either be in that screen or in both?

• The continuation screen suggests checking out the Snap! reference manual, but maybe it should have an image showing how to access it from the menubar?

• In the screen for "script variables", the OOP blurb says "new counter" - should there be an embedded image of that block there instead, like the "temp" image in the description above it? ("inherit" references it too.)

• In the screen for "inherit (attribute)", your "after" image has the direction pale, not the x position.

• One could argue that upscaled images, particularly those that are lower resolution screenshots from the days of BYOB, should not be blurred, since they weren't aliased back then and look somewhat badly filtered now. (This is noticeable in screens like "glide", "for each", and "stamp".) But I'm not sure whether that would be good or bad accessibility-wise, which should be the highest priority of course.

• I'm not sure if there's a screen for "say" yet? (No doSay.png screen, corresponding to doThink.png.) Probably should just be about the same as the "think" screen, and definitely keep the mention of "say ()" to remove the speech bubble.

• The "reset timer" screen uses a "wait (n) secs" block with a predicate inside it instead of "wait until (condition)"! (So does "get timer" - that screen doesn't have the right block in the corner, either.)

• The blocks "get tempo", "set tempo", and "change tempo" all use nearly the same help screen. I haven't looked at much of the technical details of this PR, but it looks like these each use a separate XML file; probably it's much more work than necessary to combine those, but in the translation system, is there some kind of guard against accidentally making the screens inconsistent? Maybe a note in the template, <!-- getTempo, doSetTempo, and doChangeTempo all have the same content -->? (Same for "set variable" and "change variable". There are probably other cases of this too, like show/hide variable, and maybe effect blocks, etc — might be more of a hassle to add comments than it's worth, but shrug!)

• The "stop (...)" screen could perhaps use arrows to the dropdown, like in some of the other screens?

• The "switch to costume" screen pointedly has a script description which is very literally the same words as in the script - on the one hand this is a good thing because it's probably an early help screen for readers, but on the other, maybe it isn't especially useful information? ("Wait half a second" instead of "Wait 0.5 secs" would be an easy change for instance.) A brief description of what costumes are would probably be appropriate in this screen too.

• The evaluate_list.png file is unused. It should probably either be added to the "call" screen or removed.

• The "launch" screen has a typo - "The move-and-dra script" (or the word "draw" is part covered by the image padding).

• IMO the "move 10 steps" screen should mention something about "point in direction" or "turn", because otherwise it's not clear how it's normally used - it may as well be the same as "change x by"!

• The "message" screen references "when I receive any message" - perhaps it should also be vice versa?

• getPenAttribute.png seems somewhat incomplete - it's fairly obvious what it does but the ranges diagram could maybe use a summary?

• In the "pen down?" screen, arguably it should be "if the sprite's pen is down."

• Nitpick but should there be a line break after "Sprites 2,3,4,5:" in the "go back layers" screen? :P

• The "a new clone of" screen has the exact same content as "create clone of"; while they do basically the same thing, I think it'd be better to highlight the difference with an example of using the reporter form.

• In receiveInteraction.png, the "when scripts are stopped" message has an image of a stop sign - but nothing more specific than that. Maybe it should be the stop sign button, and/or a picture of the "stop (all)" block?

• I don't think this needs to be changed; I just think it's funny that, in screens like "ask for", we say "...to fill the empty slot circled in green" when the dropdown slot is clearly indicated with a rectangle :)

• "(maybe this one.)" in reportAspect.png — 1) the period should be outside the parentheses, and 2) I think this could be a clearer message? Ala "even the sprite running this block".

• In reportBoolean.png, for your programming style tip, I believe you meant "report (foo = 0)", not "report (false)"! :P

• In reportDate.png, you probably meant "Report second within minute, 0-59" instead of "0-50".

• In reportGetSoundAttribute.png, the arrows should probably be pointing to specific options if possible, like in other help screens.

• In the screen for ">", the script doesn't fit the annotation! It should be something like "y position > 150", not "x position > 200".

• Maybe a sentence in the reportIfElse.png screen would be fitting, like "This block is useful for making compact block definitions:"? That way the image in the bottom panel isn't on its own.

• Perhaps the help screen for "letter of" should talk about / give examples of the dropdown options?

• Maybe, in the "item of" screen, there should be an "insert (score) at (1) of (top scores)" block, to make the example more complete?

• In reportMonadic.png, the script should use "set y to (100 * ...)", not "change y by".

• In reportMouseY.png, the block in the corner of the screen is "mouse x", and so is the block in the example script. Those should be changed :P

• In the help screen for "or", you're using the "and" block!

• Does "pen trails" report the trails of all sprites together? If so, the message should probably be "...does not include the stage background or any sprites themselves".

• In reportRandom.png, you probably want "set x to" and "set y to", not "move steps" twice :P

• In reportRelationTo.png, the description of the "direction" option is wrong; it reports not how much the sprite must turn, but the direction in which it must face, to be pointing towards the selected sprite.

• In reportTextSplit.png, the first example is probably meant to contain "nowhere man" (two spaces) in the input, not "hello world". Also, the "split by letter" example doesn't have an output list like the others (its image exists but isn't included in the xml/output).

• In reportTouchingObject.png, you've used the "not touching" image twice - for both the "not touching" and "touching" labels! :P

• In reportVideo.png, you could use an inline image of "point in direction" instead of the all-caps text.

• In many screens, you talk about how some effects, but not all, function for negative numbers too, and generally suggest experimenting. But in the screen for the plain "set effect" block, you don't (just saying 'type -100 to 100' on its own). It's probably worth fitting there!

• In the screen for "show", the block in the corner is "hide".

• In the turn and turn-left screens, you should probably mention "rotate this much clockwise" and "anti-clockwise", because young users who aren't familiar with those terms could easily learn them here.

• The screen for "pen up" is based on the one for "pen down", but it leaves the two additional blocks ("pen up" and another "move 10 steps") without descriptions. Those should probably be added ("stop leaving a pen trail", "move again").

• The screen for "y position" has the block "x position" in the corner.

Hope this helps!! :'D

[brianharvey]

@towerofnix Thanks for the detailed review. I've been going through them, too, and found some of your list -- but I can't believe I missed the reportBoolean one! :-/

[djsrv]

@towerofnix Thanks! It’s hard to notice errors like these after staring at the help screens for so long.

…

________________________________ From: Brian Harvey <notifications@github.com> Sent: Friday, December 27, 2019 13:00 To: jmoenig/Snap Cc: Dylan S; Mention Subject: Re: [jmoenig/Snap] Translatable XML help screens (#2456) @towerofnix<https://github.com/towerofnix> Thanks for the detailed review. I've been going through them, too, and found some of your list -- but I can't believe I missed the reportBoolean one! :-/ — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#2456?email_source=notifications&email_token=AD5OAY7VOA22OH54353TCRDQ2ZNFDA5CNFSM4IEFDBRKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEHXWBPQ#issuecomment-569335998>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AD5OAY3XCKLRQY3E7YNLPITQ2ZNFDANCNFSM4IEFDBRA>.

[brianharvey]

I have just made a PR to this PR, changing 93 files. With those changes I'm happy, although Dylan should check out Florrie's complaints just in case I missed one.

[DyslexicAwe]

Below are my changed "Move block help screen" and "Glide block help screen" which I have updated with mentioning their (in-)dependency on direction value.

and