Updating the Snap! Manual

Requests to the Community
,
1

So, I know that @bh has not been updating the manual, and this is partly because it is such a big project.

So what if the forum community were to help contribute to the manual? Would this help, @bh, or would it be too much work, in which case you might as well do it yourself?

Here is how it would work:
  1. We use github to determine all updates to Snap! since 8.0
  2. Make a checklist of all updates, and determine where in the manual such updates should be talked about.
  3. Users begin posting their updated versions of passages with the new information. In a hidden list like this one, they would write all links to previous updates, so that at the end we have a comprehensive list of what replies to look at.
  4. To make sure two people don't work on the same thing at once, a box in the checklist would be checked when that user decides to work on that passage, rather than when they are done.
2

You don't need to research github; Jens publishes very detailed release notes in the file HISTORY.md in the toplevel directory of the repo.

There are 2½ problems with your suggestion. They are

  1. The source file of the manual is a Microsoft Word document. This allows for precise placement of figures in the text, but not without fighting against Word, which thinks it's smarter than you are. As a result, even the smallest change to the manual is a pain.

1½. I have this irrational, boomer prejudice that a manual should be a paper document, or at least a virtual paper document, with pages, a table of contents, and an index. That means I end up putting as much effort into formatting as I do into content.

Just for example, if you look at the list of libraries, the order in which they are described is tweaked to try to keep those pages as full as possible, rather than any meaningful order.

  1. In my heart of hearts, I don't think anyone can write decent documentation except me. That makes it hard for me to let go.

We have a grad student at Berkeley who is allegedly working on translating the manual from Word to TeXinfo, which would allow the production of both the beautiful paper I want and the web pages everyone else wants. There is software to do this conversion, but the result is hideous, so a lot of TLC by humans is involved.

Once that's done, it'd be much easier to make the manual a github repo and let people file pull requests.

Just recently, in the thread in which we were arguing about the scope of upvars, Jens demoed an amazing feature in which, in Visible Stepping mode, Snap! will show you the scope of a variable. Nobody knew about this feature! In particular, I didn't know, which is why it's not in the manual. This depresses me. I'm sure it's in that history file, so I'd find it eventually, but updating the manual feels like the labors of Hercules.

We also want to include the SciSnap and TuneScope manuals (two important libraries) as appendices, as I did for the Colors and APL libraries. But they're their own PDFs, with their own page numbering and all that. So it's nontrivial to include them.

My plan, though, is to stop trying to do the depressing job of catching up on the small changes, and instead completely rewrite the chapter about metaprogramming -- although really before I do that, I want to make the metaprogramming library include hygienic macros, another task I've been avoiding. (And really, there should be a "make a macro" button next to "make a block" that should start something very like the block-building dialog, but the result would be a syntactic rewriting macro.)

It would be beyond wonderful if we could do the TeXinfo conversion as a community project, but I don't really see how that would work. It would end up 80% finished forever. What I want is for someone to donate enough money to hire someone full-time for a year to do all this. But yeah, if there's a way to put y'all to work on it, I'm eager to hear it.

The manual's source file is in help/SnapManual.docx in the repo, if you want to play with it.

3

I actually found this out when I had visible stepping on, and moved my mouse over a variable, however at the time I didn't realize it was the scope. That's also how I find most things, I mess around with them, and sometimes I find it by accident.

4

I remember when this got added (I was working on a complicated project that desperately needed visible stepping, and got to watch as the improvements were rolled out). It was during Snap! 9, so it shouldn't be in the manual for Snap! 8! You can console yourself with that much.

Edit: By the way, the other update made to visible stepping at that time was showing what reporters were reporting as you watched. I know you didn't know about the one update, so just in case...

5

Did you know that you can change the "anchor" of an image by turning on visible formatting symbols and then dragging the anchor symbol? This can keep images attached to the paragraph you want. Combined with using "tight" text wrapping and changing the tightness to 0.1, Word can actually do most of the work for you!

I absolutely agree that a manual should be a "paper" document (then again, I am using Word 2007 still, so I may not be the norm)!

Do they not have automatic page numbering? Is the table of contents linked to the page number rather than the section heading? Are you worried about how to copy it over (if so, you should know that Word has a built in feature for appending two Word documents)? Or is there something else causing troubles?

6

https://github.com/jmoenig/Snap/blob/master/HISTORY.md

8.1.0:

  • New Features:
    • visually highlight variable scope when mouse-hovering over a variable declaration in visible stepping mode
    • visually highlight the variable declaration of variable accessor blocks when mouse-hovering over them in visible stepping mode
    • show intermediate results when debugging a script, i.e. when clicking on a script in visible stepping mode. Thanks, Vic!
7

What again does the principle of hygienic macros offer that couldn’t otherwise be achieved within reasonable time and effort using a procedure ? Any examples?

8

Oh, I'm sure I can do it using the existing metaprogramming features. That's why it goes in the library.

So, the virtue of lexical scope, as Jens has been reminding us, is that you can determine the scope of a variable just by reading the code, without knowing what procedure is calling the procedure you're reading. This is as opposed to the situation with dynamic scope, in which the same variable name, in the same procedure, may refer to two entirely different variables on two calls to the procedure.

But this simple rule doesn't work in the case of macros, because a macro writes code that has to be run as if it were located in the procedure that calls the macro.

So the idea of hygienic macros is to make the variables in macros well-behaved with respect to scope, so that it doesn't cause trouble if the same name is used in the macro and in the procedure that calls the macro. Basically what you do is that every time you call the macro you change all of the variables in its scope to unique generated symbols. (Something similar is done when applying logic programming rules.)

There are more details, e.g., once in a while you want to capture a variable of the caller, so there has to be a way to exempt some variable names from this renaming process.

9

Yeah, as I said, Jens's release notes document every detail. I would eventually have learned about this feature while working through them.

10

What I have is PDFs, not Word files, for those libraries. I'm sure each of these problems is solvable! It's just, you know, another brick in the wall.

I know about anchors, but haven't had as much luck as you apparently have had at moving them and attaching them to things. No doubt there's a Word manual I could read that would teach me how to do everything.

But, you know, if you keep giving me Word advice, you might find yourself conscripted as a volunteer on this project! :~P

11

While you were typing I rephrased my question: what do hygienic macros offer that ordinary procedures don’t, and do you have any application examples in mind?

12

I knew about variable scope, I remember reading about it the day it was implemented and giggling and then trying to implement top from logo and getting frustrated because snap doesn't handle variables like logo.

So it's another one of those features I can't use because it's gate kept behind ancient text languages.

13

Sorry I fell asleep just as you said that! :~/

The question really is what macros offer that etc. Hygienic macros are just macros that aren't prone to certain bugs that otherwise happen with old-school macros.

Since v10 we can already do everything macros do; they just offer maybe a more natural notation for
untitled script pic (4)
(or RUN similarly).

There are only a few cases in which you really need a macro. If you put a variable in the ... slot, you get dynamic scope, i.e., access to a variable of your caller. If you put REPORT in there, you can report a value from your caller. If you put SCRIPT VARIABLES there, you can create a variable in your caller's context.

But, more commonly, you use a macro to invent a notation. For example, if we only had
mastermind-stream script pic
and you wanted to invent
untitled script pic (6)
you could write it as a procedure:

untitled script pic (7)
untitled script pic (7)926×444 57.4 KB

except that certain action scripts wouldn't work, namely, those with REPORT or SCRIPT VARIABLES or anything else that has to be in the caller's context. You could fix that by saying
untitled script pic (8)
untitled script pic (8)926×492 76.6 KB

but it'd be a better user interface if you could say
untitled script pic (9)
untitled script pic (9)1202×432 61.3 KB

where in that first input to REWRITE you could use long form input dialogs to set the types of the inputs to the command you're rewriting. (And also we took care that if the caller of IF/ELSE happens to have a variable named TRUE CASE that wouldn't mess things up.)

That's a macro.

14

Thank you for explaining. I've now read this older topic, too.
IMAO introducing macro-making functions wouldn't add much value to Snap!'s already very powerful metaprogramming capabilities. It might be better to document current functions (such as
untitled script pic (89)), and their applications, really well.

Two functions that would be needed for hygienic macros would actually be useful anyway:

  1. pattern matching (I built one for logc programming, based on SICP);
  2. create unique variable names (I think I have one too).

Plus I can think of several other candidate functions for metaprogramming library. New topic?

15

Aw, c'mon, now. This is how every of our internal discussions ends: There is a genuine task that needs to be done, here: Update the documentation to the current version of the software. Then it gets side-tracked and reformulated into a "Oh, before we do that we want to engineer some abstruse hobby" (hygienic macros). And next thing is somebody is going to want to twist my arm into changing the scope of variables to accomodate special cases of their abstruse hobby (gensym var names), and when I'm reluctant to that there will be massive pressure about this built up here. In the meantime nobody outside 2 people ever uses any of these super urgent features, and this is why things don't get done, and why documentation trails behind.

16

@jens, ad: your lastest post - it was marked as a reply to my previous post, but perhaps it was meant to be directed at @bh? Especially the reference to "internal discussions" hints at that.

Speaking for myself only: I happen to agree with you on hygienic macros, and on the priority of a documentation update. As for variable scope I still believe it ought to be as local as possible, but I wouldn't dream of urging anyone to implement such change aSAP. :slightly_smiling_face:

17

As a foundation for the hygenic macros, a ring formal parameters may be used but... should it work that way?
untitled script pic (4)
I'd rather expect "".

18

Oh yes, good point, sorry!

19

No problem!

20

I don't know. Perhaps @bh?