doc: Consolidate Makefile targets around {build|install}-{format}
authorW. Trevor King <wking@tremily.us>
Sat, 5 Apr 2014 17:17:03 +0000 (10:17 -0700)
committerW. Trevor King <wking@tremily.us>
Sat, 10 May 2014 16:49:23 +0000 (09:49 -0700)
commit4fb5447805a8d5bb8da74c0196f12ac4ffaf4394
tree22adbe1634a10f5b589d90305941ce57b13757fd
parentacb1c6dc1128eaefe0a8def82da7800727716139
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
Makefile.local
doc/INSTALL
doc/Makefile.local