On Sat, Apr 05, 2014 at 05:35:49PM -0300, David Bremner wrote:
> W. Trevor King writes:
> 
> > -- 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-

Ah, looks like that happended in with the original Sphinx code in
d736260 (doc: convert sphinx based docs, 2014-01-28).  It looks like
the current usage is (from the .PHONY entries):

  {build|install}-man, which is backend (Sphinx/Docutils) agnostic
  sphinx-{html|texinfo|info}, which doesn't have an install target

Is that distinction intentional?  Personally I prefer the consistency
of:

  {build|install}-{man|html|texinfo|info}

if the configured backend (Sphinx/Docutils) doesn't support the
requested target, we should error out.  If no backend is detected,
build-man and install-man should be pulled from the default dependency
tree (but they would still error out if you called them directly).  If
that sounds reasonable, I can work up a patch.

> > -- 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

Oops, thanks.

> > -Building the man pages
> > -----------------------
> > +Building the man Docutils
> > +-------------------------
> >  
> 
> + with

Thanks again :p.

> > -- 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

Ok.

> Finally, I don't really object to rewriting doc/INSTALL in rst, but
> I wonder if we should rename it to INSTALL.rst

Sure (I don't really mind).

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy