Add pandoc-based man pages generator

[evgenyz]

Man pages are generated from the contents of README.md file.

It will be useful for packagers and would allow to have a handy help in form of git sha --help.

[radmen]

@evgenyz I'm not familiar with pandoc. How this can be used to generate a valid man page for git subcommands?

[evgenyz]

@evgenyz I'm not familiar with pandoc. How this can be used to generate a valid man page for git subcommands?

Install pandoc, run readme2mans (from this PR). You'll have a bunch of *.1 files.

[radmen]

@evgenyz I've missed your changes :facepalm: Thanks for the details!

[radmen]

I've checked if I can bundle the script in the AUR package. I can confirm that the provided script generated valid man pages for the commands.

[evgenyz]

I've checked if I can bundle the script in the AUR package. I can confirm that the provided script generated valid man pages for the commands.

Any suggestions for improvements?

[radmen]

@evgenyz I know little about the subject. All I had to do was executing your script and gziping the *.1 files.

On the users perspective - I think it makes sense to "ungroup" the git-merged / git-unmerged / git-merge-status section.

The git help merged, git help unmerged and git help merge-status commands work as expected however the whole man page looks odd (the first paragraph mentions something about "trio of subcommands"). I guess it's something that could be changed in the README file.

[evgenyz]

@nvie Are you on board with this idea?

[nvie]

I ran this locally to try it out, but I end up with a directory filled with "empty" man pages inside the repo. They all contain this content:

.\" Automatically generated by Pandoc 2.10.1
.\"
.TH "" "" "" "" ""
.hy

I didn't dig in just yet as to what may be going on here.

Taking a step back though. I like the idea of having man pages, but I'm not sure if generating them from READMEs is going to be the best idea. If I would like to add man pages, I'd like them to be first-class citizens and put the time and dedication in there to make them high-quality and useful — like people expect from man pages — rather than generate them from the "oneliners" in the current README. The README is intended to provide a quick overview (hence the one-liner style to describe them). For man pages, I'd love to provide a more extensive documentation — something more akin to the "usage" help you get when running -h (but even more extensive/elaborating). That (level of) documentation is currently not available. (And the README isn't the place for that either.)

I'm currently thinking that -h is "good enough" until we'd have this more extensive documentation. Also, adding man pages means all package managers (brew, AUR, apt-get, etc etc) will all have to know about it and be updated. I'm not sure if it's all worth the trouble in this case.

That's not to say I don't appreciate this effort, I do! 🙏

[evgenyz]

Hmm, hmm.

Let's take git-cleanup and git-is-repo as an example:

Without man pages:

[evgenyz@Latutude ~]$ git cleanup --help
No manual entry for git-cleanup
[evgenyz@Latutude ~]$ git-cleanup -h
usage: git cleanup [-nh]

Deletes all branches that have already been merged into the main branch.
Removes those branches both locally and in the origin remote.  Will be 
most conservative with deletions.

Options:
-n    Dry-run
-s    Squashed
-l    Local branches only, don't touch the remotes
-v    Be verbose (show what's skipped)
-h    Show this help

[evgenyz@Latutude ~]$ git is-repo --help
No manual entry for git-is-repo
[evgenyz@Latutude ~]$ git-is-repo -h
[evgenyz@Latutude ~]$ 

With auto-generated man pages:

[evgenyz@Latutude ~]$ git cleanup --help
GIT-CLEANUP(1)                                                  GIT-CLEANUP(1)

NAME
       git-cleanup (git cleanup)

DESCRIPTION
       Deletes  all  branches that have already been merged into master or de‐
       velop.  Keeps other branches lying around.  Removes branches  both  lo‐
       cally  and  in the origin remote.  Will be most conservative with dele‐
       tions.

GIT TOOLBELT
       Part of the git-toolbelt(1) suite.

AUTHORS
       Vincent Driessen.

git-toolbelt 1.5.0                2020-09-12                    GIT-CLEANUP(1)
[evgenyz@Latutude ~]$ git-cleanup -h
usage: git cleanup [-nh]

Deletes all branches that have already been merged into the main branch.
Removes those branches both locally and in the origin remote.  Will be 
most conservative with deletions.

Options:
-n    Dry-run
-s    Squashed
-l    Local branches only, don't touch the remotes
-v    Be verbose (show what's skipped)
-h    Show this help
[evgenyz@Latutude ~]$ git is-repo --help
GIT-IS-REPO(1)                                                  GIT-IS-REPO(1)

NAME
       git-is-repo (git is-repo)

DESCRIPTION
       Helper function that determines whether the current directory has a Git
       repo associated to it.  Scriptable equivalent of git repo.

GIT TOOLBELT
       Part of the git-toolbelt(1) suite.

AUTHORS
       Vincent Driessen.

git-toolbelt 1.5.0                2020-09-12                    GIT-IS-REPO(1)

[evgenyz@Latutude ~]$ git-is-repo -h
[evgenyz@Latutude ~]$ 

I think that it worth some effort (which is pretty small, just another command for pages generation in the package specs).

Also, while one could ship the README.md file in the package, it is not really convenient for console usage. This generator could evolve in the future and generate man pages from a full-blown MANUAL.md file, nice and shiny.

[nvie]

OK, I guess it's not that big of a deal to support, and you're right: this can grow organically and start sourcing from a dedicated MANUAL.md eventually. I do however want to add a few things here to automate before checking this in now. I want to set up a Github Action for this that automatically builds these man pages using pandoc and automatically checks the results into source control. Any update the README should then automatically become a change to one of the .1 files, so they can't get out of sync.

I'll need to carve out some time to properly automate this, hopefully later this week.

[evgenyz]

Well, what I had in mind with this script is the ability to build man pages automatically during the packaging process, without having .1 files in the repository. This way you don't have to sync them, all changes in README (and later on MANUAL) would end up in man pages if the packager has a desire to do so (this would add just one build-dep, pandoc).

But then it is better to check somehow that resulting pages are sound (and this is where GH Action might come handy, as a sort of gating test for README).