doc/INSTALL: Remove rst2man reference and other updates

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 RST2MAN=/usr/bin/rst2man.py DESTDIR=/tmp/ install-man

  works for me.

diff --git a/doc/INSTALL b/doc/INSTALL
index e37c2b9bd4b1af22e7b48f25597c0b9ca6dd4a20..91222f908c37bf62c414720af2a59207041f94d7 100644 (file)
--- a/doc/INSTALL
+++ b/doc/INSTALL
@@ -1,24 +1,30 @@
 This file contains some more detailed information about building and
 installing the documentation.
 
-Building with sphinx.
----------------------
+Building with Sphinx
+--------------------
 
-- You need sphinx at least version 1.0.
+With Sphinx_ version 1.0 or greater, you can build man, info, html,
+and pdf versions of the docs (currently only the man pages) with::
 
-- You can build build and install man pages with 'make install-man'
+  make build-{man|info|html|pdf}
 
-- You can build man, info, html, and pdf versions of the docs
-  (currently only the man pages) with
+You can build build and install the docs (currently only the man
+pages) with::
 
-     'make install-{man|info|html|pdf}'
+  make install-{man|info|html|pdf}
 
-Building the man pages
-----------------------
+Building the man Docutils
+-------------------------
 
-- You can build the man pages with rst2man (from python-docutils) with
-  'make rst2man'.
+If you don't have Sphinx installed, you can still build the man-page
+version of the docs using rst2man (from Docutils_)::
 
-- Currently there is no support to automagically install the resulting
-  nroff files, but it should work to modify the target install-man
-  in doc/Makefile.local.
+  make build-man
+
+and install with::
+
+  make install-man
+
+.. _Sphinx: http://sphinx-doc.org/
+.. _Docutils: http://docutils.sourceforge.net/