Generate man file from README.rst

[KeithHanlan]

Currently, end-users have only terse usage help for git-fat. In order to get the full documentation, they require the README.rst file which is not part of the installation.

The Makefile could be enhanced to create man/man1/git-fat.1 using rst2man.

Ideally, the sections on installation would be omitted and the other sections would be re-ordered to follow the usual man-page arrangement.

Alternatively, write a separate git-fat.rst file, stealing data from the current README.rst.

[abraithwaite]

I'm not sure how you'd install it though. I'm not aware of how to configure setup.py to copy the man page to the man pages location, and I don't particularly want to be responsible for maintaining packages for a bunch of different distributions/OSes

[KeithHanlan]

The current Makefile doesn't provide the conventional rule for "install". It shouldbe trivial to add using the usual conventions. (make [PREFIX=/opt/local] && make install)

I am completely unfamiliar with pip and its manpage doesn't provide much guidance.

I will investigate furrther.

[KeithHanlan]

I've looked into this a bit further and am dismayed to discover that python distributions do not natively include support for RST formating in the same way that Perl supports POD. RST is nicer but the support for it is not ubiquitous. Currently anybody and his dog can install git-fat; if I introduce a dependency on Sphinx, docutils, and/or rst2man, that would no longer be the case. Any suggestions from more experienced python developers would be welcome.

[justinclift]

Hmmmm, if the README file was in Markdown, would that make it easier?

[KeithHanlan]

I'm not sure @justinclift . Isn't Markdown rather github-specific? I could write a normal manpage using any number of different markup languages (including troff) but I was hoping to take advantage of the README.rst file which is already human readable. Ironically, if I were to just rename the file git-fat.1, man would still feed it to "nroff -man" and make a mess of it.

I rather like RST; I'm just disappointed that rst2man isn't part of the python distribution.

[justinclift]

@KeithHanlan "Standard" Markdown is extremely widespread. GitHub added support for it due to that (then tweaked their own version a bit).

Only asking because (I think) Markdown might be more widespread than RST, so there might be more chance of the right tools already being around.