Explain the differences in using shebang vs scala-cli directly in script

[lwronski]

Fixes #1309.

[Gedochao]

LGTM

[SethTisue]

Can we do better than shebang on the name? It seems like obscure jargon to me

[Gedochao]

Can we do better than shebang on the name? It seems like obscure jargon to me

@SethTisue any suggestions for an alias?

I actually don't think it's that obscure of a jargon...
The current shebang sub-command has 2 main use cases:

• to be used in the shebang header, as per the Unix standard, for which the name seems appropriate;
• to be used from the command line with legacy syntax backwards compatible with the old scala runner.

Although I believe we'll be keeping the shebang name, as the former usecase is the main one, I think we could potentially have an alias to make it easier to guess the second one... provided that we can think of a good name for it, of course.
Would something like run-legacy do the trick? feels verbose to me...

Also, I wonder if an alias is even necessary... if a user cares about backwards compatibility in this context when migrating from the old scala runner to Scala CLI, then it's probably fair to assume he's a rare specimen of a power user. Which means he should probably be okay with obscurely named sub-commands...

We don't want to promote using shebang from the command line for regular users, they should just learn the run syntax.

[Gedochao]

@SethTisue I created a dedicated discussion for the shebang naming in #1755, let's continue that topic there