Separate documentation pages

[hkdobrev]

I would like hub to have separate documentation pages (a.k.a. man pages) for each hub command. Just like git does.

When one types hub help browse the whole hub documentation pops up and the user needs to find the description and available arguments for the desired command.

Someone might even use a hub command without knowing he's using hub. In this case when he types git help browse, he will see some documentation which is not directly related.

[mislav]

When one types hub help browse the whole hub documentation pops up and the user needs to find the description and available arguments for the desired command.

Fully agreed. However, most hub commands are overloaded git commands. What would we show when someone types git help checkout? I wouldn't show our own documentation, because that would mean replicating git's own documentation.

This is the primary reason we sticked with a single man page for hub until now. I welcome suggestions how to improve this, but you must keep in mind that we don't want to mess with git's own functionality.

[hkdobrev]

IMHO git help checkout should show the git checkout documentation.

hub help checkout should show a documentation for its changes to git checkout. It should have a prominent note on the top saying you are using hub and urging you to type git help checkout if you need the docs for the rest of the git checkout functionality.

[mislav]

hub help checkout should show a documentation for its changes to git checkout

One problem: when hub is aliased to git, we can't know which command was originally typed by the user. So we can't discern between hub help and git help

[hkdobrev]

I'm not very familiar with the exact way hub wraps git, but it should be
fairly simple to check $1.

[hkdobrev]

Sorry, meant $0.

[mislav]

@hkdobrev:

$ cat > hub <<<"#\!/bin/bash
echo hello from \$0"

$ ./hub
hello from ./hub

$ alias git=./hub
$ git
hello from ./hub    # expected "git"

$ bash -c 'exec -a moo ./hub'
hello from /full/path/to/hub   # expected "moo"

[hkdobrev]

@mislav I was wrong :)

However I think I've found the dumbest way to check how hub was called.

Using history with something like this:

echo `history 1` | cut --delimiter=" " -f 2

[mislav]

It's an original idea, but I wouldn't use it. I wouldn't work if someone has history disabled, and it will likely not work when shelling out of Ruby because the inner shell is not guaranteed to match the outer, interactive shell

[hkdobrev]

@mislav Does this mean we would not have separate man pages, because of implementation limitations? There must be a way! 😄

[mislav]

Of course there's a way. We can have separate documentation pages, but not under hub help COMMAND syntax. Other suggestions welcome

[hkdobrev]

We could use something like man git-checkout and man hub-checkout. Users should be educated about this approach though.

[mislav]

We could use something like man git-checkout and man hub-checkout.

That's a pretty good idea. The hub install process could install the
individual hub-* man pages, and there would be no hacks involved to
making this happen.

[mislav]

This was done in #1087 and will be part of 2.3 release!