search

alire-project / alire

Command-line tool from the Alire project and supporting library
GNU General Public License v3.0
278 stars 49 forks source link

Alr command line help needs help #1150

Open Joebeazelman opened 2 years ago

Joebeazelman commented 2 years ago

Alr command line syntax is way too confusing, difficult to remember, and counterintuitive. First, there's a help command with the following syntaxalr help [command]; and then there's a help flag written as alr [command] --help or alr [command]. A user who needs help shouldn't have to figure out whether the two different invocation forms are the same or different. It's also cruel to require usage grammar for the command form. Placing the help after the command is misinterpreted. The command form of help offers no utility other than upholding UNIX's longstanding tradition of user hostility and confusion.

While the help displays the commands with a brief description, it offers no help for the command options. Issuing alr help -c, for instance, doesn't help. What is in the configuration folder? How do I specify the path with quotes or no quotes, etc? alr help config shows various configuration options, but doesn't show any examples to clarify them to the user. Modern computer users frequently cut and paste commands into the terminal and change arguments to avoid carpal tunnel syndrome. In fact, there should be examples everywhere. Not theoretical examples, but real-world ones such asalr config --set editor.cmd code --global.

Finally, the most useful and simplest part of Alire is the interactive configuration or assistant. It should be an available option for all commands and featured prominently where it cannot be overlooked by the user. Expecting users to type in pathnames and issue long chains of arguments is user abuse from a bygone era. Users who need to express their manliness and intimidate their rivals are free to self-flagellate using Alire's commands and flags. The rest of us want to focus on the programming at hand, not the tool.

onox commented 2 years ago

Alire's command line interface isn't really that much different from other command line programs. It provides options and commands. There are many programs that do this. The issue reads as a rant against command line programs in general.

The --help flag is used by many programs to display some help text. The same applies for the help command.

it offers no help for the command options. Issuing alr help -c, for instance, doesn't help.

The description is printed after the option: -c (--config=ARG) Override configuration folder location. In the case of -c, the text could be improved a bit by adding something like See help of command 'config' for details.

How do I specify the path with quotes or no quotes, etc?

This sounds like something that depends on your shell.

How do I specify the path with quotes or no quotes, etc?

An 'EXAMPLES' section below the 'DESCRIPTION' section could be added to some of the commands.

the interactive configuration or assistant. It should be an available option for all commands and featured prominently where it cannot be overlooked by the user. Expecting users to type in pathnames and issue long chains of arguments is user abuse from a bygone era.

Forcing the user through some wizard for every command would be very awkward and user interaction disables programmatic use of commands. It would also cause Alire to severely deviate from how other package managers behave and therefore increase the learning curve.

Joebeazelman commented 2 years ago

Alire's command line interface isn't really that much different from other command line programs. It provides options and commands. There are many programs that do this.

I would tell you that the UNIX standard should not be emulated, but it doesn't have one. Every UNIX application I've encountered has its own flavor. Alr's command line syntax is very similar to dotnet core's syntax. It even has the double dashes for option and the help as a command. It also suffers from the same problem. Is this a new standard being adopted?

Forcing the user through some wizard for every command would be very awkward and user interaction disables programmatic use of commands. It would also cause Alire to severely deviate from how other package managers behave and therefore increase the learning curve.

I didn't say the interactive command line should be the default behavior. It should be provided as an option the user is fully aware of. For instance, if the user types the wrong command, they should be prompted to see if they want to enter the interactive mode.

The issue reads as a rant against command line programs in general.

I'll give you more rant than you can handle! Back in the 1980s I saw the Macintosh and immediately knew it would be the future of computing. It's now 2022 and we're still using the command line. What's worse, we're not even using the friendlier VMS or even Multics variety, but the most user-hostile one from that era simply because it requires less effort to implement. UNIX and its open source culture promote mediocrity.

I made a point to tell Brian Kernighan what I felt about UNIX when I first met him. To my surprise, he agreed. He said UNIX wasn't intended to be a finished product. It was supposed to be a quick and dirty operating system. It escaped the lab into the wild, but most developers didn't bother to improve its usability since it wasn't supposed to be a consumable product.