search

lord63 / tldr.py

A python client for tldr: simplified and community-driven man pages.
MIT License
186 stars 18 forks source link

Suggestion: syntax streamlining #24

Closed nkahe closed 7 years ago

nkahe commented 7 years ago

This is a good client but following CLI syntax would IMO be an improvement. Note: COMMAND refers to which command's tldr page user wants find.

Usage: tldr COMMAND [OPTIONS] [ARGS]...

Options:
  -i, --init     Init config file.
  -l, --locate   Locate the command's man page.
  -r, --reindex  Rebuild the index.
  -u, --update   Update to the latest pages.
  -V, --version  Show the version and exit.
  -h, --help     Show this message and exit.

So any argument that's not an option would be considered as a command user wants to find. Advantages: for majority of time I strongly suspect user wants to find a command's tldr page. This syntax is streamlined, shorter and more predictable (to guess/remember without reading help): instead of 'tldr find ls', 'tldr find ssh', 'tldr find tar' you can use 'tldr ls', 'tldr ssh', 'tldr tar'. Other functions than finding tldr page are much less used so they could be used as options like above. For example: rebuild index: 'tldr --rebuild' or 'tldr -r'.

lord63 commented 7 years ago

Thank you for you suggestions. As you said, if we choose tldr COMMAND, in most use cases, it is shorter and easy to type. Actually, when I choose a subcommand, I also want to pick a short and easy-remember name.

But I'm afraid that I won't switch to this behaviour, because:

  1. it's a break change and I don't want to introduce it;
  2. I still prefer subcommand(the way I use now), just like git commit, git rebase. For some complicated cli apps, it is good and easy to extend. For tldr.py, in my opinion, rebuild, find, reindex are different features and they don't fit into the arguments case.