doc: Consolidate Makefile targets around {build|install}-{format}
The rst2man target was removed in
9d9a700 (doc: build man pages at
build time; introduce HAVE_SPHINX, HAVE_RST2MAN, 2014-03-13), but a
reference in the install docs slipped through. While I was removing
that reference, I also:
* Converted doc/INSTALL to reStructuredText, so I can link to Sphinx
and Docutils directly. Not everyone has access to Debian's
python-docutils, so it's better to be genric here.
* Converted from an unordered list to paragraphs, because I think it
flows better.
* Dropped the rst2man no-automatic-install caveat. I don't think this
applies to the current code, although I haven't tried to track down
a commit that adds the automatic-install support. Anyhow,
$ make HAVE_SPHINX=0 HAVE_RST2MAN=1 RST2MAN=rst2man.py DESTDIR=/tmp/ install-man
works for me.
* Restructured the Makefile to use build- and install- prefixes
consistently, regardless of Sphinx/rst2x backend.
* Instead of disabling the build-man and install-man targets if
HAVE_SPHINX and HAVE_RST2MAN are both empty, just pull build-man and
install-man out of the default build tree. That way:
$ make HAVE_SPHINX=0 HAVE_RST2MAN=0 build-man
will fail like it should, instead of successfully doing nothing. If
packagers *do* want to force building the docs, despite any config
settings, you can override the BUILD_MAN and INSTALL_MAN variables:
$ make BUILD_MAN=build-man all