From: David Bremner <david@tethera.net>
To: "W. Trevor King" <wking@tremily.us>, notmuch@notmuchmail.org
Subject: Re: [PATCH 7/7] doc/INSTALL: Remove rst2man reference and other
	updates
In-Reply-To:
 <edf9a674bc1f41917caead8d38b5f09295a9d1bd.1396718720.git.wking@tremily.us>
References: <cover.1396718720.git.wking@tremily.us>
	<edf9a674bc1f41917caead8d38b5f09295a9d1bd.1396718720.git.wking@tremily.us>
User-Agent: Notmuch/0.17+170~gf516b7c (http://notmuchmail.org) Emacs/24.3.1
	(x86_64-pc-linux-gnu)
Date: Sat, 05 Apr 2014 17:35:49 -0300
Message-ID: <874n271plm.fsf@maritornes.cs.unb.ca>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: list

"W. Trevor King" <wking@tremily.us> writes:

> 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.
> ---
>  doc/INSTALL | 34 ++++++++++++++++++++--------------
>  1 file changed, 20 insertions(+), 14 deletions(-)
>
> diff --git a/doc/INSTALL b/doc/INSTALL
> index e37c2b9..91222f9 100644
> --- 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}

most of those those targets now start with sphinx-
>  
> -- 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::

build build
>  
> -     'make install-{man|info|html|pdf}'
> +  make install-{man|info|html|pdf}
>  

this is not your bug per se, but while we're fixing docs, most of those
targets don't exist.

> -Building the man pages
> -----------------------
> +Building the man Docutils
> +-------------------------
>  

+ with

> -- 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.

This should mention the relevant variables, since the targets are the
same in both cases

Finally, I don't really object to rewriting doc/INSTALL in rst, but I
wonder if we should rename it to INSTALL.rst

d