Does usage have to be able to show a single command?

[ghost]

Given the following structure, I thought it’d be useful to show the commands similarly in usage. However, this would make it rather odd & difficult when showing help for a single command (as opposed to a whole group), especially when the command doesn’t use one of the arguments. Would it hurt if it showed help for the whole group instead?

Single-day commands
    --at
    {SINGLE_DAY_ALIAS}
    --category
  show
  add
    --note
  edit
Range commands
    --from
    --to
    {RANGE_ALIAS}
    --category
  log
    --[no-]pager
  search
Category commands
    --category[-name]
    --category-description
  add-category
  set-category-description
  rename-category
Arg-less commands
  order-categories
  list-categories
copy
  --from
  --to
  --category
Stup-info commands
  usage
    {COMMAND}
    --[no-]pager
  version

--category (& given my other effort, later also --[no-]pager) could also be as a general argument, since only arg-less & stup-info commands don’t use it; what do you think about this? And what about the general idea of structuring the help?

[iridakos]

I do believe that we should structure the help 👍

My only concern is that we two will do understand the suggested output, but new users would prefer to see what each command supports as options following the common "usage" structure most scripts use.

What do you think?
Can you give me an example of what the usage output for the add for example would be to see if I understand correctly your suggestion?

[ghost]

It would probably look like this. I’m now re-creating the description completely, of course the old text will be reused for the most part. Also ignore that the lines aren’t wrapped correctly.

$ stup usage add
add is a single-day command.

Single-day commands
  Common arguments
    @|-@|--at <date>     Indicates the date to operate at, either in the format %Y-%m-%d (2020-11-16) or as an alias (see below)
    <day-alias>          These can be used without --at. Allowed aliases: today, yesterday, tomorrow
    -c|--category <cat>  Indicates the category to use, instead of the default category.
  show
    Shows notes in the given category for the given day. If no category is specified, shows notes from all categories (not just the default).
    No additional arguments.
  add
    Adds note(s) to the given category for the given day.

    -n|--note            Specifies the note to add, can be used more than once
  edit
    Allows you to manually edit the category's notes file for the given day.
    No additional arguments.

A little harder is it for category commands, where we’d probably have to write the allowed arguments (without their description) for each of the commands. Describing them like used if there's no category of that name & used for an existing category is also possible though.

new users would prefer to see what each command supports as options following the common "usage" structure most scripts use

To be honest, at least to me the current state is rather confusing (if I stup usage w/o a command, which is my preferred way).

Also, I’ve just realised that there is nothing like stup usage commands to just shortly list all the available commands. Maybe that should be the default & detailed help shown on stup usage all

[ghost]

I just want to remind you of this — I'm not doing it until I know what it should look like according to you. Have you forgotten again? Or do you not have enough time or energy?

The reminder also applies to other recently active issues.

[iridakos]

Hello @tiosgz , I'm a little busy these days. I'll get back to you asap. Thanks!