search

racket / scribble

Other
197 stars 90 forks source link

Refactor blueboxes name to signature-box #286

Open nloadholtes opened 3 years ago

nloadholtes commented 3 years ago

Simple find-and-replace to change the name for blueboxes to signature-box.

(Quick note: this is my first time messing with racket, so apologies if anything is incorrect/wonky/etc.)

Followed the steps outlined #206 and then ran the tests using raco test scribble-test and saw them all pass with racket version v7.9.0.22 [cs] on Ubuntu 20.04

sorawee commented 3 years ago

While I agree with the renaming in general, please keep blueboxes.rkt (and re-export stuff from the new module) because other programs might still be using it! For example, @greghendershott's Racket Mode requires it, so this change as it is would break his program.

Similarly, I'm not sure if renaming the Scribble file name is a good idea. Someone might link to https://docs.racket-lang.org/scribble/blueboxes.html literally, and this change would break the link.

rfindler commented 3 years ago

I agree with @sorawee -- we probably don't want to change any of the existing files or exported names. I think it makes sense to change the documentation to call them "signature boxes" and it may make sense (but is less obviously good) to add new files that just reexport the existing functions under new names (or to rename the existing files and then add backwards compatibility files).

As for the error message -- I think you probably want to work with a more recent version of Racket before trying to investigate that too deeply. Assuming you have build-essentials installed (and maybe a few other packages) you should be able to simply do git clone https://github.com/racket/racket.git; cd racket ; make (get coffee) and then mkdir extra-pkgs ; cd extra-pkgs ; raco pkg update --clone scribble and then you should be able to work with the right code. hth.

nloadholtes commented 3 years ago

Great point @sorawee about the external dependencies, I will re-work this PR to prevent breakages.

And thanks @rfindler about the version, as soon as I typed in that used apt-get I thought "That is probably the worst way to install racket for this work..." :laughing:

shhyou commented 3 years ago

This tutorial by Ben may help: Tutorial: Contributing to Racket

nloadholtes commented 3 years ago

Thanks to @shhyou and @rfindler I built racket and re-tested. The tests pass now. I'll turn this PR into a draft PR while I work on the changes requested.

greghendershott commented 3 years ago

Not to talk past the close, but, changing the required module name and function names would break more things than just Racket Mode.

I totally agree that "bluebox" has been kind of an obscure term ever since the docs got a new style sheet, years ago. :smile:

So I definitely think there's merit to changing the docs to help. Like maybe define "bluebox" as a tech term, and/or add both "bluebox" and "signature-box" as index terms, and so on.

greghendershott commented 3 years ago

Dang I can't recall the raco command. Maybe I imagined that.

Anyway, here's one list:

https://github.com/search?p=2&q=blueboxes-cache&type=Code

That list isn't perfect.

It's too long because it includes many forked repos (although some of those forks might need to be changed, eventually).

It's too short because it's only code on GitHub.

But generally speaking Racket "never" removes modules or files, and breaks existing programs. It might add new, preferred alternatives, or aliases.

nloadholtes commented 3 years ago

Thanks @greghendershott! I had no idea this code could have such far reaching impact. :smile: I appreciate all the pointers on this from everyone.