Add manpage during/after installation to enable `--help` in subcommand mode

[HeapUnderfl0w]

When using a program as a subcommand in git (as in git global) git will intercept all calls to --help, and attempt to display its own help message. For that it attempts to fetch the corresponding manpage.

Due to git-global not providing its own manpage at the moment, all calls to help will fail:

$ git global --help
No manual entry for git-global

A current work around is to call git global directly with git-global --help which gives the expected help page, but its still a gotcha that requires retyping the command "just" for the help page.

A simple solution would be to have a subcommand that spits out the manpage for the user to put where its discovered properly by man.

[peap]

Thanks for filing! This sounds like a good idea.

I'll point that git global help and git-global help currently work, too, displaying the same output as git-global --help . Adding a man page would make make more permutations work, as well; we'd have seven ways to find help at that point (with checkmarks for the ways that currently work):

• ✔️ git global help
• git global --help
• git help global
• git --help global
• ✔️ git-global help
• ✔️ git-global --help
• man git-global

rust-lang/rfcs#2376 indicates that Cargo itself doesn't offer man-page installing functionality, so your idea about a git-global subcommand to do the installation seems reasonable. git-global already uses clap, so clap_generate looked promising, but I don't think it supports manpage installation yet, just bash completions.

I'll take a little time to look around at how other Rust binary projects are solving this.

[peap]

git-series is another Git subcommand written in Rust that has a process to install its man page described here: https://github.com/git-series/git-series#building-and-installing. They recommend cargo install into a non-default root directory, then copying the man page to a specific directory.

[HeapUnderfl0w]

git global help

ah! perfect, that works too of course (i probably missed that option)

Adding a man page would make make more permutations work, as well

Yea that would work. Honestly i think its only really nessesary to:

• a) have a manpage avaliable somewhere in the repository (so maintainers / packagers can grab it and install it to the correct locations if nessesary. this would be especially good on diststributions like NixOS, which package software quite differently).
• b) optionally have a subcommand that puts the manpage in a default location (~/.local/share/man/man1/ if the documentation at the git-series link is correct)

these options would offer in my opinion the best of both worlds. git-gobal doesnt need to worry about specifics of the os (as the default location should be standard), and maintainers / packagers can modify stuff if nessesary.

(PS. i am mentioning packagers often here because i do plan to create a derivation for my private nixos later)

[peap]

Thanks for the extra details and proposal.

Ideally, I'd like to add something to the codebase that emits manpages based on our clap::App, so that the metadata and list of subcommands don't have to be further duplicated. There's an open issue about manpage generation for clap (clap-rs/clap#552), but it's not ready yet. Nevertheless, I'm optimistic that we can add a generator function that translates the App to a manpage that can be committed to the repo and optionally installed by an end user at runtime. The man crate seems promising.

I've started looking at how to write manpages in general, and I'd like to try supporting both the traditional format and HTML (for git-bash on Windows). I can't commit to a timeline, but I'll keep this issue updated. I'm happy to review PRs, as well!

[peap]

I might try something with https://crates.io/crates/clap_mangen in the future, and I haven't gotten around to an HTML page yet, but I'm going to merge my branch into master so that a generated manpage exists there, and can be updated as we go.