raco install is a common beginner error with a confusing error message

[jackfirth]

What version of Racket are you using?
e.g., 7.8 [3m]

What program did you run?

raco install rebellion

What should have happened?

New users do this often enough when trying to install a package for the first time that I think there should be a special case error message like the following:

The package management commands are all grouped under "raco pkg".
Did you mean "raco pkg install rebellion"?

If you got an error message, please include it here.

/Applications/Racket v7.8/bin/raco: Unrecognized command: install

Usage: raco <command> <option> ... <arg> ...

Frequently used commands:
  docs                 search and view documentation
  make                 compile source to bytecode
  setup                install and build libraries and documentation
  pkg                  manage packages
  planet               manage Planet package installations
  cover                a code coverage tool
  doc-coverage         a code documentation coverage tool
  exe                  create executable
  test                 run tests associated with files/directories

A command can be specified by an unambiguous prefix.
See `raco help' for a complete list of commands.
See `raco help <command>' for help on a command.

[sorawee]

I sympathize but disagree with the proposed solution.

"Did you mean" works great for correcting queries like raco pjg to raco pkg (based on, say, lowest edit distance). I don't think it should be used to correct the kind of errors that you are talking about.

Personally, I think the current hint (Frequently used commands) works great already. Is it the case that you saw people still confused after reading the hint?

[jackfirth]

Yes, because the current hint doesn't list raco pkg install as a frequently used command, just raco pkg. It's not obvious to new users that raco pkg install exists. Installing packages is one of the most commonly used commands, so I think it's reasonable to have some special casing for it.

[sorawee]

Would it help to reorder "Frequently used commands" to have pkg at the top (it's not alphabetically already anyway), and use the description "manage packages (e.g., install, remove, update)".

"planet" probably should be removed from the list. It's no longer a frequently used command, and having too many items could make users disinterested in reading the hint.

[jackfirth]

I think revisiting the contents and order of the list could help, but I'm not sure I understand the argument against the kind of error message I'm proposing. What would be the harm?

[mflatt]

Maybe raco should allow plugins to provide a list of commands that 1) promise to just print a suggestion to stderr, and 2) are used as fallbacks only if no other tool implements the command. So the pkg collection could provide install (or maybe all of its subcommands) as fallback tools that print the suggestion to use raco pkg <subcommand>. If some plugin one day implements install, it will not have been taken over by pkg. Or if some other plugin one day provides an install fallback, both suggestions would be printed to stderr.

[jackfirth]

I definitely like that approach in the long term. I don't have bandwidth to design something like that anytime soon though. In the short term, is there a simple special case fix we could do that wouldn't require designing a general approach? The two options I can think of are:

1) Make a raco install command that just prints out the error message we want

Pros: straightforward and would take little time to implement. Cons: if some package author wants to make their own install command, they have to reach out to us first and get us to replace the quick fix with something more general. Also, the command would show up in the list of commands printed by raco help. @mflatt - is there a way to suppress that?

2) Write some special case code in raco for this

Pros: no new APIs required. Cons: it's confusing for the raco implementation to have special-purpose code for one specific command, when in all other respects it's designed to avoid knowing about specific commands.

I lean towards option 1, since it would get the job done without totally breaking abstraction barriers. Open to suggestions.

[sorawee]

Maybe raco should allow plugins to provide a list of commands that 1) promise to just print a suggestion to stderr, and 2) are used as fallbacks only if no other tool implements the command.

The first step is to extend raco-commands in info.rkt so that we can specify this information. The problem is that currently raco-commands is a list of length exactly 4. What's the best way to extend it?

Also note that in the current list of length 4, the "prominence" field is practically optional (though it's technically not). So we might as well really make it optional in the new interface.

One possible interface is:

(define raco-commands `(,val1 ,val2 ,val3 ,val4 #:suggestions ("install" "remove") #:other-optional-field ,valN))

We could also go all-in:

(define raco-commands `(#:command ,val1 #:path ,val2 #:desc ,val3 #:prominence ,val4 #:suggestions ("install" "remove")))

Another possibility is:

(define raco-commands `([command ,val1] [path ,val2] [desc ,val3] [prominence ,val4] [suggestions ("install" "remove")]))

For the latter two, the list of 4 values must still supported for backward compatibility. prominence and suggestions are optional as mentioned earlier.

[samth]

I think a hash makes the most sense here.

[mflatt]

I'll just note that this strategy seems different from what I had in mind. If you annotate existing commands with #:suggestions, then I think that means raco has to come up with the message to report the user — something that says that maybe pkg should be used in place of install, but I don't think raco is going to be able to be very specific.

I had in mind adding a separate raco-fallbacks, or something like that, which would cause raco to run collection-provided code for a fallback. Then, the message to report is up to the code that implements the fallbback.

There's the usual trade-off here between a DSL for commands (and having raco always/increasingly do the right thing) versus extensibility through arbitrary code.