ofiwg/libfabric — pull request #320 by jsquyres (2014-11-14 17:53:52+00:00)
Title: New nroff man pages generated from gh-pages/man via pandoc

These man pages are generated from the Markdown man pages on the gh-branch, in the `man` directory. Pandoc is used to generate these pages from the Markdown pages.

I'm not entirely pleased with how Pandoc is indenting the code Synopsis section at the top, but I'm not quite sure how to fix that.

Accepting this commit means that we will change the workflow for libfabric man pages:

1. The Markdown man pages in the `gh-pages` branch is the One Canonical Source of Truth. I.e., all changes to man pages will be made in the Markdown pages on `gh-pages` (note: you can still do pull requests on the `gh-pages` branch).
1. A cron job will run (at Cisco for now, but it can run anywhere) that periodically examines the `gh-pages` branch for changes to the Markdown pages. It generates a new nroff man page for any Markdown man page that was changed, and commits that new nroff man page into the libfabric `master` branch.

Hence, all the nroff pages in `master` will always be generated, and will always be within N hours of being in sync with the Markdown pages on the `gh-pages` branch.

Sidenote: N should be, at most 24, IMHO. But it can be more frequent than that.