improving in-terminal help

[Daniel Montague]

I found tab today; it's pretty slick!

The readme is well done (thanks!), and the examples right off the bat are a nice change from the normal command line tool "options first' approach.

Once you're in the terminal, ready to use tab, the -h output isn't as friendly, and jumping from a terminal to a browser or lessing the readme is a bit awkward.

Could some of the readme be merged into the -h output? as a tab newcomer, it would help tremendously!

[Ivan Tkatchev]

Could some of the readme be merged into the -h output?

That's certainly a good idea. Which part do you think should be merged?

P.S. What OS do you use?

[Daniel Montague]

From what I've seen so far

• an overview of the options (already there)
• a short description
• examples
  • @'s role
  • some common functions used with @
  • very simple use of comprehension and sequences
• "hard" data
  • syntax rundown
  • an index of functions
  • syntactic sugar rundown

One thing that helps me grok new stuff is multiline examples refactored down to one liners. This would be really nice, especially in tab's case, perhaps not in -h, but maybe the readme?

But i guess this is just my two cents and everyone learns differently, so i'll cut it there.

I don't see any contributing info; how would you feel about a pull request for any of this?

---

Linux for the OS. I'm on Ubuntu 14.04 — and on that note, I couldn't build tab "out of the box" because I had 4.8.
If you want to add a note for Ubuntu LTS users, it was a handful of commands to get tab built:

sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install g++-4.9
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.9 10
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-4.9 10

(with the caveat that that might not be the best approach; It worked for me, but I don't have much c experience)

[Ivan Tkatchev]

how would you feel about a pull request for any of this?

No problem, please do send pull requests!

This would be really nice, especially in tab's case, perhaps not in -h, but maybe the readme?

Yeah, that kind of stuff is supposed to go into the man (or info) pages. Except that nobody reads info pages and the practice of putting complex documentation into man pages (like Perl does, for example) is super-confusing.

[Daniel Montague]

Except that nobody reads info pages and the practice of putting complex documentation into man pages

agreed completely, and it would be a split from the otherwise self-contained binary.

What about mirroring the verbosity flags' style with something like -h -hh -hhh?

[Ivan Tkatchev]

What about mirroring the verbosity flags' style with something like -h -hh -hhh?

Probably a good idea. I think I saw something like this somewhere, but can't remember where...

[Ivan Tkatchev]

Merged a preliminary version into master. (See 2.1 release.)