Add synopsis autogenerator

[Kubuxu]

Generates synopsis automagically

Few examples:

ipfs add [--recursive | -r] [--quiet | -q] [--silent] [--[no-]progress] [--trickle | -t] [--only-hash | -n] [--wrap-with-directory | -w] [--hidden | -H] [--chunker=<chunker> | -s] [--[no-]pin] [--] <path>...
ipfs pin ls [--type=<type> | -t] [--quiet | -q] [--] [<ipfs-path>...]

License: MIT
Signed-off-by: Jakub Sztandera kubuxu@protonmail.ch

[whyrusleeping]

oooOooo, fancy! you should throw in a couple tests

[Kubuxu]

I will.

[Kubuxu]

@whyrusleeping tell me if that is enough, if it is not then I will work more on it.

[whyrusleeping]

That works for me.

[Kubuxu]

@RichardLitt I would like to hear your opinion and also possible improvements if you see any.

[RichardLitt]

This looks great to me!

I can't think of any improvements, at the moment -- would be good to run this and add the output for each command to this PR? That way we can see how it works and upload the changes now, as opposed to after merging.

[Kubuxu]

If we remove synopsis from command now it will be replaced with the generated one. We could remove all of them from code, generate all help texts and go through them improving them (with SynopsisOptionsValues map). How does it sound?

[RichardLitt]

Sounds good to me. I think that makes more sense than merging this before doing that.

[Kubuxu]

All synopsis in existence: https://gist.github.com/Kubuxu/09b0ef346b469001ca51f6e345d79a33

[Kubuxu]

Synopsis lines can get quite long, should we do anything about it?
Example:

ipfs add [--recursive=<recursive> | -r] [--quiet=<quiet> | -q] [--silent=<silent>] [--progress=<progress> | -p] [--trickle=<trickle> | -t] [--only-hash=<only-hash> | -n] [--wrap-with-directory=<wrap-with-directory> | -w] [--hidden=<hidden> | -H] [--chunker=<chunker> | -s] [--pin=<pin>] [--] <path>...

[Kubuxu]

Now with synopsis generator also would be great to go through codebase and make longer options definitions the primary ones (create as first instead of e).

Or I could also check which is the longest and use that one in the generator. What do you think?

[whyrusleeping]

@Kubuxu i think we should standardize on the options being specified a certain way. Making the 'first' one the primary, and the second the alternate

[Kubuxu]

WHOO, finally tests are green. Will work on moving those parameters around now.

[Kubuxu]

@RichardLitt re: gist: I could make the description in case of bool options a bool. Or maybe some way to show default value.

[RichardLitt]

I could make the description in case of bool options a bool. Or maybe some way to show default value.

That should work. The default value should always be specified by .Default(false) for bools - we can see if there's any issue with that once generated? Happy to go through each and nitpick.

[Kubuxu]

Only problem I have is how to show it?
[--progress=??? | -p ]

[RichardLitt]

How about just [--progress | -p]?

Like this:

10:28 ~/src/community (feature/add-repo-links) 🐕  man git-add

GIT-ADD(1)                        Git Manual                        GIT-ADD(1)

NAME
       git-add - Add file contents to the index

SYNOPSIS
       git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
                 [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]]
                 [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing]
                 [--] [<pathspec>...]

[whyrusleeping]

the synopsis generation LGTM. I'm still not super sure what i think of the --no- prefixing... Lets wait for a little more input on that on the issue about this before merging.

[Kubuxu]

@whyrusleeping removed the no- prefixing.

[whyrusleeping]

@Kubuxu i pulled this down to try it out, but --help is hanging on a bunch of commands due to the stdin thing. Lets get that fixed first and then i'll merge this in

[whyrusleeping]

(the few commands i ran that didnt hang looked great 👍 )

[whyrusleeping]

@Kubuxu could you rebase this one?

[Kubuxu]

Rebased.

[whyrusleeping]

LGTM!

[RichardLitt]

YASSSSSSSS

[jbenet]

• This is great
• But a problem: one of the goals for synopsis was to give users a very clear example of the top 1-3 commands they would be running, like the simple usage: that you see in many commands. With a full synopsis, that's not there anymore, so we need to either:
  • prioritize examples and suck it up that they dont show on short -h
  • allow a different usage: thing to exist.
• Compare git merge -h (the usage at the top) and git merge --help (the full synopsis).

---

--no- prefix

Never, please never use --no- prefix. It's written down elsewhere, but the gist is that double negatives absolutely suck, and are very, very confusing for people. It's also confusing having to remember which option (positive or negative) exists. It's much cleaner to establish an invariant that always options are positive, and if they default to true, you can turn them off with --thing=false.

[jbenet]

I think we need our short usage back, like git merge -h:

> git merge -h
usage: git merge [<options>] [<commit>...]
   or: git merge [<options>] <msg> HEAD <commit>
   or: git merge --abort

    -n                    do not show a diffstat at the end of the merge
    --stat                show a diffstat at the end of the merge
    --summary             (synonym to --stat)
    --log[=<n>]           add (at most <n>) entries from shortlog to merge commit message
...

[jbenet]

this could be explicitly chosen per command, and not auto generated, it's ok.