Is it the case that documentation for a library mylib should go into the subcollection scribblings/mylib?

it’s not necessary. Personally I like keeping the docs close to the source (though I still use separate files)

You can configure this in the info.rkt file

I find myself parameterizing with (parameterize [my-par (my-par)] ...). Is this foolish? The lack of a short form for this makes me suspicious.

Can’t you leave that clause out? You seem to keep the value.

The other day I needed a default value. That became: (parameterize ([my-par (or (my-par) 'default-value)]) body)

The first expression in the body is to a function that will change my-par. After that there is more stuff that can fail with an error. I want to retain the original value of my-par if it does. (This is for interaction using the REPL.)

It feels like (let [x x] ...), which always rubbed me the wrong way also…

I’m not sure what you mean. If the body of parameterize escapes, such as through an exception, the parameter value is still the same outside the [dynamic extent of the] parameterize.

I could be misreading the docs, but Guide 4.13 says “When control leaves the https://docs.racket-lang.org/reference/parameters.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._parameterize%29%29\|parameterize form—either through a normal return, an exception, or some other escape—the parameter reverts to its earlier value”.

What I want to do in general is “do some stuff which changes certain things, but if the doing fails, the changes are undone”.

The doing is triggered by a single expression in the REPL, and the undoing has to happen by the time control returns to the REPL.

Ah, you want to imperatively update the parameter value. it turns out that (parameterize ([x x]) ….) won’t let …. update the parameter value from the perspective of outside the parameterize. It creates a fresh binding with its own state.

I think you’ll have to use dynamic-wind or a prompt handler to revert state on an escape. There’s not really a pretty way to do what you want, I think.

(But maybe I still don’t understand.)

No, I think what you are saying is fine. So if I (my-par new-val) in the body of the parameterize, it holds for the rest of the (dynamic extent) of the body, right? And calls to functions outside the body that get/set my-par also have their changes reflected in the body on return? But when we reach the end of the body and leave the parameterize expression, the old value is restored. (That’s okay for my purposes, because, and I didn’t say this correctly, the changes in my-par shouldn’t persist, though the body of parameterize is computing something that should be made persistent, which is delivered as its result.)

I am escaping the body only by error, so I could install an error handler to do something similar, but that is messier, I think. I don’t think I need dynamic-wind.

I think I get it now, and (parameterize ([my-par (my-par]) …) does the seem the way to go. Like (let ([x x]) …), it says “state will be used, but should be confined here”, and I don’t have a better form for that.

Thank you very much!