Add a man page

[orhun]

Is your feature request related to a problem? Please describe.

A man page should be added to the project for accessing the documentation using man(1):

$ man git-cliff

Describe the solution you'd like

Add a man page under docs/ in the root directory of the project. It should contain information about the command line arguments, configuration file sections/fields and the basic usage.

There are 2 possible ways that I can think of to achieve this:

• Add the markdown representation of a man page (for readability) and use a 3rd party tool for conversion.
  • docs/git-cliff.md
  • Tools for conversion: pandoc or mandown
  • README.md should be updated about conversion instructions.
• Add the groff file
  • docs/git-cliff.1
  • help2man(1) can be used for assistance.

Describe alternatives you've considered
None.

Additional context
None.

[alerque]

One potential alternative would be to port from structopt to Clap — which can work very nearly the same but is also a bit more flexible. There are already ways to convert the --help output it generates to man pages, but there is also progress on it's internal manpage generation: clap-rs/clap#552

[alerque]

Updates on my comment above:

• Clap v3 is out. It now directly consumes StructOpt structs, so porting should be easy.
• Man page generation isn't there yet, but there is WIP.

[grawlinson]

There is clap_mangen now. 🎉

[orhun]

I added a man page generation script in 03d55c8. Man page can be generated and viewed like this:

OUT_DIR=$(pwd) cargo run --bin git-cliff-mangen
man ./git-cliff.1

[alerque]

I think this should probably go in build.rs, possibly behind an on-by-default feature flag so people that don't want to compile the dependency crates don't have to. The matching man page can then be considered a standard artifact of the build process.

... of course if you follow my logic too far you have to wrap Rust projects in a proper build system like autoconf so everything gets installed to the right places depending on the system without putting the burden on distro packages to reinvent the wheel to spin up everything by hand in each upstream project.

[orhun]

I think this should probably go in build.rs, possibly behind an on-by-default feature flag so people that don't want to compile the dependency crates don't have to. The matching man page can then be considered a standard artifact of the build process.

I think I'm going to leave it as is for now. Completions are also generated with the same approach.