Create man page to enable git help absorb

[nilbus]

Overview

This PR introduces a man page for git help absorb. Fixes #2. Content was largely adapted from the existing README and --help output.

Without a man page for git-absorb, both git help absorb and git absorb --help produce this error:

No manual entry for git-absorb

Although git-absorb --help does show a help page, the syntax required for this to work atypical and unconventional.

New users are likely to easily forget the wording of --and-rebase. I would find this help page useful. See also #2.

Viewing the man page without installing

You can preview the man page without moving it into a system man directory via

man ./Documentation/git-absorb.1

Editing the man page

Documentation/git-absorb.txt contains the human-readable source for the man page. It uses the asciidoc format, which you can largely pick up by copying the style already used in the source file. If you need more advanced text formatting, titles, lists, etc., see the asciidoc user guide.

To build the man page after editing, run make. This requires that you have asciidoc installed.

The version number in the man page must be updated for each new release.

Man Page Installation to System

As @giodamelio pointed out, the cargo community is still working on a solution for installing man pages. I recommend following that discussion and adding support to this project's cargo.toml once support becomes available.

In the meantime, the man page can be installed via the homebrew formula. I have patch ready to be submitted as a pull request once a version of git-absorb is released that contains the man page. I've tested this patch successfully locally.

diff --git a/Formula/git-absorb.rb b/Formula/git-absorb.rb
index 4db7db5dfc..a8024a9bd8 100644
--- a/Formula/git-absorb.rb
+++ b/Formula/git-absorb.rb
@@ -16,6 +17,10 @@ class GitAbsorb < Formula

   def install
     system "cargo", "install", "--root", prefix, "--path", "."
+
+    man_path = File.join(prefix, "share", "man", "man1")
+    mkdir_p man_path
+    cp "./Documentation/git-absorb.1", man_path
   end

   test do

[nilbus]

I've posted a preview of what the rendered help/man page in this gist: https://gist.github.com/nilbus/78549c85ad0282425ee78f52a9263b2d

[tummychow]

i would much rather pull something out of clap than generate the manpage separately with asciidoc, but given that i'm too lazy to write it myself, i will merge this PR as a matter of principle. much appreciated

[nilbus]

Thanks. I’m not sure how I would approach making a man page from clap docs, but that’s a neat idea.

FYI, because of homebrew’s stance on installing documentation that upstream (cargo install) doesn’t install, there may be no reason to release a new version containing the man page. https://github.com/Homebrew/homebrew-core/pull/45533#discussion_r336734949

I’ll let you know if that changes.

[gasche]

Note: I installed git-absorb through cargo today (it is not yet packaged on Fedora) and immediately ran into the issue that git absorb --help does not work. After looking at this issue, here is the workaround that I used:

wget https://raw.githubusercontent.com/tummychow/git-absorb/0.6.6/Documentation/git-absorb.1
mv git-absorb.1~/.local/share/man/man1