--help flag is near useless
lolbinarycat opened this issue · comments
The help flag doesn't really tell you how thing work. There are a number of issues:
- No distinction between literal input and a description of accepted input.
For example thedone
subcommand:doing [global options] done [command options] entry
Hereentry
(a description of what that argument is) anddone
(the literal string "done") are given no differentiation. - No explanations for arguments
While flags have a nice synopsis, the same cannot be said for other arguments.
Take my previous example, what doesentry
mean?
Is it:
- the exact body of an entry to mark
- a numerical offset
- the name of a section
- the name of a tag
- the exact date of an entry
- the literal word "entry"
Who knows?
There's more, but I don't really feel like listing everything right now, so I'm just going to leave it there.
I think you’re thinking of documentation. - Brett
I don't think I am. And if there is documentation, it should be linked to by help
(ls
does this). Having documentation does not excuse having help
's output be sloppy and unclear.
if there is documentation
I've found the doing
README to be quite extensive. Maybe I've spent most of my time around a set of outlier repos, but having the full documentation live on the readme and keeping the --help
to a quick reminder of the flags is entirely standard in my view.
Respectfully, if you think the readme should also be reflected in ruby docs or something, you could volunteer your time to submit a pull request, @lolbinarycat, just like Brett has volunteered his time to build this whole project.
I may submit a PR, although I might be more inclined to do so if I knew anything about ruby, but I'll give it a shot.
can anyone point me to the file that contains the help function?
what defines the desc tags? I want to add text to the bottom of the help
output, but that doesn't seem to be possible.
You have to consider that in the years doing has existed, no one has ever had the issue with the help system that you have.
Noone has mentioned having the issue, you mean. I would imagine most people would just not use it if they didn't understand. It's what I already did, last time I installed this.
Ok, again, I apologize for my crankiness. I appreciate you trying to help. The main description is found in bin/doing on a line starting with 'program_desc'. You can also add a longer description that will appear beneath that short description using program_long_desc '[long description, including line breaks and urls]
as documented in the GLI rdocs. If you just want to add a link to the project page or GitHub readme, you can let me know what you're thinking and I'd be happy to just insert it for you.
At this point, I think just redirecting people to the README
file is the best course of action.
Just to put a bow on this, variables are now all-caps in the help, e.g. doing [global options] now [command options] ENTRY
, which should be a standard enough convention to avoid confusion. I've also added an EXAMPLES section to the help for all commands.