--help flag is near useless

[lolbinarycat]

The help flag doesn't really tell you how thing work. There are a number of issues:

1. No distinction between literal input and a description of accepted input.
   For example the done subcommand: doing [global options] done [command options] entry
   Here entry (a description of what that argument is) and done (the literal string "done") are given no differentiation.
2. No explanations for arguments
   While flags have a nice synopsis, the same cannot be said for other arguments.
   Take my previous example, what does entry 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.

[Brett Terpstra]

I think you’re thinking of documentation. - Brett

…

On Sep 2, 2020, 2:50 PM -0500, lolbinarycat ***@***.***>, wrote: The help flag doesn't really tell you how thing work. There are a number of issues: 1. No distinction between literal input and a description of accepted input. For example the done subcommand: doing [global options] done [command options] entry Here entry (a description of what that argument is) and done (the literal string "done") are given no differentiation. 2. No explanations for arguments While flags have a nice synopsis, the same cannot be said for other arguments. Take my previous example, what does entry 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. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[lolbinarycat]

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.

[Brett Terpstra]

I welcome anyone else’s input, but I disagree with most of your premise. If you read the documentation, the prompts provided by the help system make perfect sense. Linking the documentation is feasible, but how did you find this project if not through either the project page on my site or via here (GitHub) where the readme is quite detailed? This is a personal project I give away for free. I don’t owe you anything, and your insulting and entitled tone is not going to prompt any changes. - Brett

…

On Sep 2, 2020, 7:16 PM -0500, lolbinarycat ***@***.***>, wrote: > 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. — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[Vinney Cavallo]

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.

[lolbinarycat]

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.

[lolbinarycat]

can anyone point me to the file that contains the help function?

[Brett Terpstra]

The help is generated from the desc tags in the main doing file. Each command has its own, and the main banner is defined in bin/doing. - Brett

…

On Sep 3, 2020, 11:57 AM -0500, lolbinarycat ***@***.***>, wrote: can anyone point me to the file that contains the help function? — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[lolbinarycat]

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.

[Brett Terpstra]

It is not. - Brett

…

On Sep 7, 2020, 12:09 PM -0500, lolbinarycat ***@***.***>, wrote: 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 are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[Brett Terpstra]

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. But if you really feel the world needs this change, see the documentation for GLI. - Brett

…

On Sep 7, 2020, 12:09 PM -0500, lolbinarycat ***@***.***>, wrote: 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 are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[lolbinarycat]

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.

[Brett Terpstra]

Which is fine. I lose zero dollars when someone can't take the time to read the docs and abandons the project. I'm really not normally this much of a dick. It's just an old project that I've put a lot of time into but which currently has zero of my attention. My personal life has me crabby right now, so I'm not treating this with the concern I would one of my commercial projects. I'm just not up to dealing with it. Sorry off I come off as aloof or harsh. - Brett

…

On Sep 7, 2020, 4:36 PM -0500, lolbinarycat ***@***.***>, wrote: > 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. — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[Brett Terpstra]

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.

[lolbinarycat]

At this point, I think just redirecting people to the README file is the best course of action.

[Brett Terpstra]

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.