search

jmoenig / Snap

a visual programming language inspired by Scratch
http://snap.berkeley.edu
GNU Affero General Public License v3.0
1.49k stars 742 forks source link

Two improvements to Export Summary #1439

Open brianharvey opened 7 years ago

brianharvey commented 7 years ago

Background: We are working on solutions for BJC labs, which teachers desperately want. We clearly have to provide the solutions as Snap! projects, so that teachers can run the solutions and students can try modifying them. But we think teachers also want a more readable format. Export summary is a good start toward making one, but would require a good bit of manual reordering so that, for example, the block definitions that make up one problem will appear together, and also together with examples of using the blocks. But manual reordering means that we have to maintain two versions of the solutions, which means version skew and assorted nightmares.

So here is the proposal to fix this. I think kids making reports for their AP portfolios would also benefit.

  1. Introduce a notation for "put X here." I'm thinking one way might be some Other-category pseudo-blocks that don't do anything in Snap! but do in Export Summary: defn means to insert the definition of the block at this point in the summary (instead of where it usually goes). (Note that we need either two versions or a form of procedure input that accepts both commands and reporters.) reportfrom puts a shift-right-click expression-and-value picture in the summary.

    I'm not wedded to this pseudo-instruction block thing as the notation for these formatting tools. Even better would be if we could drag blocks into comments and then parse comments starting with keywords such as DEFINITION followed by a block. (Being able to drag blocks into comments would be great altogether!) Or, you know, right-click something that makes a weird graphic in the scripting area that isn't clickable but does affect Export Summary. Whatever.

  2. Comments that are attached to scripts should be unchanged, but free-floating comments between scripts (vertically) should be changed into

    ..., and collapsed (one line boldface) ones should be changed into

    ...

    . This makes them bigger and more readable.

I haven't convinced everyone yet that this is the way to go, but supposing I do, could it be implemented reasonably soon?

jmoenig commented 7 years ago

Ugh. Adding more "notation" to Snap just for the sake of producing dead documents (which we all agree we hate and only add for the sake of stupid formal documentation requirements) from live projects, seems like a bad idea to me.

brianharvey commented 7 years ago

Aww, don't think of it that way. Think of it as Knuth's "Literate Programming" for Snap!.

jmoenig commented 7 years ago

:-)

stirlingstout commented 7 years ago

I like the idea, as it makes Snap! an easier 'sell' to educators and assessors, but I don't like the idea of other blocks to do the arranging. As far as examples of using a block are concerned I put those in the block definition (see first attachment) since such 'floating' blocks are saved correctly: I hope this is a feature and that I can depend on it in the future).

I also use a [comment [] []] block (see second attachment) to 'comment out' code but that's not really relevant here.

I'd really like an Export summary as text... option like BYOB had. If it's text then I can do the rearranging later.

Alternatively (I don't know if this is a really stupid suggestion) what about ordering the blocks automatically? I know there will be some degenerate cases.

snap1 snap2

jmoenig commented 7 years ago

As far as examples of using a block are concerned I put those in the block definition (see first attachment) since such 'floating' blocks are saved correctly: I hope this is a feature and that I can depend on it in the future).

Oh, that's a feature for sure! It wasn't possible in BYOB and it took me a while to implement it in Snap, but it's absolutely crucial :-)

stirlingstout commented 7 years ago

Oh good, because it's really useful.

Get Outlook for Androidhttps://aka.ms/ghei36

On Thu, Oct 6, 2016 at 6:59 PM +0100, "Jens Mönig" notifications@github.com<mailto:notifications@github.com> wrote:

As far as examples of using a block are concerned I put those in the block definition (see first attachment) since such 'floating' blocks are saved correctly: I hope this is a feature and that I can depend on it in the future).

Oh, that's a feature for sure! It wasn't possible in BYOB and it took me a while to implement it in Snap, but it's absolutely crucial :-)

You are receiving this because you commented. Reply to this email directly, view it on GitHubhttps://github.com/jmoenig/Snap--Build-Your-Own-Blocks/issues/1439#issuecomment-252037877, or mute the threadhttps://github.com/notifications/unsubscribe-auth/ACEABylzR81wbipLxXqd0KXeq1JnzxOEks5qxTS5gaJpZM4KKd5s.

This email was Virus checked by KGV Sophos UTM. itservices@kgv.ac.uk

[King George V Logo] John Stout Management Information Systems Coordinator Tel: 01704 530601 E-Mail: JSS@kgv.ac.uk Web: www.kgv.ac.uk

Information contained in this e-mail is intended for the use of the addressee only and is confidential. Any dissemination, distribution, copying or use of this communication without prior permission of the addressee is strictly prohibited.

Every effort has been made to ensure that any attachment to this mail does not contain virus. King George V College has taken every reasonable precaution to minimise this risk, neither it nor the sender can accept liability for any damage which you sustain as a result of software viruses. You should carry out your own virus checks before opening any attachments.

[Think Before You Print]

brianharvey commented 7 years ago

Making the examples subordinate to the definition is great for doing demos in front of the class. But it doesn't make for a narrative flow in project documentation; the author has to be able to intersperse text, examples, and definitions in arbitrary orders. And in particular it doesn't put example-reporter-with-result-balloon pictures in the document.

jmoenig commented 7 years ago

We really need a better way for media-rich mash-ups in or next to code, e.g. pictures, drawings, free-form text etc.

brianharvey commented 7 years ago

It'd be a help if you could drag things into a comment -- mainly code, but also those other things.

jmoenig commented 7 years ago

Yes, that's a good next step, and it would be easy to implement, except that we'd also need to make text flow around those embedded elements, which is currently hard to do. Perhaps we could start just with the embedding part...