man page contains wrong version number

[imphil]

The man page of git absorb (v0.6.9 as available from GitHub releases for x86) says it's version 0.5.0 from 2019:

git-absorb/Documentation/git-absorb.1

Line 10 in 764f477

.TH "GIT\-ABSORB" "1" "10/18/2019" "git\-absorb 0\&.5\&.0" "git absorb"

I guess there's some automation missing to update the docs with the correct version number when doing a release?

[tummychow]

tsk, i don't use asciidoc myself so it's rather inconvenient for me to bump and regenerate that every time. and i'm sure as hell not editing groff by hand. i'll see if there's an easy way to fix this

[tummychow]

(for the record, there haven't been any interface changes since the man page was written, so it's not actually out of date, it's just annoying that groff expects every manpage to have the version and date in the footer)

[iwittkau]

I just noticed that

  -F, --one-fixup-per-commit               Only generate one fixup per commi

is missing from the outdated man page help which is also used when executinggit help absorb.

[tummychow]

ugh that's because i've been forgetting to ask people to update it when they add new features. i also don't use adoc personally (and frankly i suspect most contributors don't) so we should probably regenerate the groff in a github action and attach it to a release object. more housekeeping...

[reivilibre]

This bit me (the version number being wrong + not including the -F flag I specifically was hoping to find in the man page).

A friend noticed that https://crates.io/crates/clap_mangen is a thing; thought I'd suggest it in case exporting the help from clap is preferable to editing the roff. (Maybe this could be done in the GitHub Action or whatever). I've not tried it myself though.

[tummychow]

oh, good idea. i would accept a pr to switch to clap_mangen, but probably won't get to implementing it myself any time soon

[blairconrad]

For what it's worth, I did the simplest possible thing to use clap_mangen to generate a man page, and the results were mixed. The new flags are output, but custom documentation such as fancy description, a distinction between flags and options, usage, and configuration were lost. It's possible they can be recovered, but the clap_mangen docs that I found weren't incredibly detailed.

I tried copying (for now) some of the git-absorb.txt information into documentation in main.rs, where clap can see it, and was able to have it appear in the man page, but the formatting was lost. Maybe smarter people than me can figure it out, but I think you get "big blob of text".

I further dug and clap_mangen emits only select sections, although there's a note about how you can use parts of it to generate roff which you can embed into your own custom roff, which (to me) sounds painful.

Since there's more documentation than just command-line arguments (detailed (and formatted) usage notes, the CONFIGURATION section, and so on), I don't think clap_mangen is going to solve everything. For my money, even though asciidoc isn't the most well-known format, it's at least easy to read and to make additions to. I'd suggest some combination of

1. auto-generating the man page from the .txt file. Technically only needed for releases, but I'd be inclined to do on every build and attach as a build artifact (and maybe even the result of formatting the man page as text) so people could see how it looks and also we could detect doc-building failures before release
2. a PR template with a checkbox to remind people to update the .txt file if public-facing arguments, config, or whatever are changed

As usual, since I'm weighing in, I'd be happy to attempt whatever variant of changes you liked.

[tummychow]

hm, unfortunate... well thanks for the attempt. ci to regenerate the asciidoc would also be accepted. in the future we can move it to a release attachment and take the roff file out of the repo entirely