There should be a swagger-like standard for command-line tools... 🤔
What do I mean by that?
Wouldn't it be great if tools provided an interface to an automated documentation of their own command-line parameters and flags?
This could be used to provide interactive help while typing on the prompt, as well as accurate auto-completion in your shell.
@fribbledom maybe we could hook this into man pages.... and autocomplete that checked man would rock.
I'd almost look at it the other way round:
Let the man pages be generated from the self-documenting feature of the tools! 👌
@fribbledom If it gets me man pages again for this infuriating slew of new commands, I'll take it!
@fribbledom The first time I really learned Linux, was by having discovered the xman command .. and reading the /entire set/ of man pages on the system, encyclopedia style, front to back, while trying out everything I could. I have no idea how I would do something like that on a modern system.
The problem is that only options are really specified similarly enough that it's parsable. Subcommands and other kinds of arguments are specified differently in each.
E.g. the kinds of files or commits a `git` subcommand takes just aren't automatically translatable from the man page.
Also the option descriptions are often too verbose to show in completions.
@fribbledom now you made me wonder how it works in zsh 🤔
@fribbledom Many libraries for cli tools now provide autogenerated --help and even autogenerated bash completion scripts!
@fribbledom AutoCAD, for all its many faults, is a bit of a model here in that you can move back and forwards between menu selections, dialog boxes and mouse actions to and from writing a command in a box at the bottom.
As you do the mouse actions it shows you the equivalent command in the command box.
As you type a command it prompts you to fill in the appropriate data, e.g., a point on the screen which you can click on or type the coordinates.
Would be great to have a shell like this.
@fribbledom fish sort of does this already. It has a built in completion format and comes stock with a load of completion information for things like core utilities and very common programs. There are also several packages that provide fish completions for other specific programs, or you can write your own too.
They're great because not only do they provide completion, but they also attach a brief description of each option, so with a keybind (double Tab iirc) it'll show you the docs for each option.
@fribbledom Isn't it called getopt?
That's a common way to retrieve the flags, yeah. It's neither self-documenting nor accessible through an API though.
I think you misunderstand what I want.
I want apps to be able to return a JSON (or XML or TOML or whatever) definition of their own command-line syntax, so other things (like your shell's auto-completion feature, for example) can process that information to provide a better user experience.
@fribbledom So, I did. I was probably thinking about apps when I read tools. Thank you for calling my attention.
Python's ability to let an IDE do just that is one of the main reasons I don't want to use anything else these days.
@fribbledom this would be amazing, let's start a task force and get it done
@fribbledom Doesn't fish do something similar?
@gudenau @fribbledom I expect fish lets you define external meta-data for commands (similar to the autocomplete files for bash, zsh, etc). But the point here is to have a standardized way for a command to emit its own metadata.
This way, autocomplete and documentation could work out of the box on any shell that supports the standard, no external definition necessary.
@fribbledom It would be nice if the command args would appear as a fly-out menu to the terminal you were in. Yes, I can tab between terminals where one is the man page and all, but its small things that improve the user experience, I find.
Server run by the main developers of the project It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!