[issue1746] doc: rst2man not directly available all platforms

[Michael Springmann]

New submission from Michael Springmann <michael.springmann at unibas.ch>:

In changeset http://selenic.com/repo/hg/rev/d6eecafaf12f (doc: use 
reStructuredText for man and HTML pages), building Mercurial documentation 
now requires docutils and the manpage-writer.

For Debian-based distributions, this should be easy to solve by simply 
installing packages docutils and docutils-writer-manpage from repositories.

For other systems, more manual work might be required. In particular since 
manpage-writer from the docutils sandbox does not provide a proper 
installer by itself (whereas the tarball of docutils clearly does) and the 
sandbox itself is described in th README as
"The Sandbox is a place to play around, to try out and share ideas. The
sandbox/ directory is a part of the Subversion repository but it isn't
distributed as part of Docutils releases.
It's OK to make a mess in the Sandbox! But please, play nice."

There is no support for setuptools yet and therefore it means that by 
switching from asciidoc to rst2man, installing Mercurial on a machine now 
requires manually installing some tools as a prerequisite since building 
the documentation is part of "make all". 

For instance, on Mac OS X, to my best knowledge, there is:
- rst2man not included in default installation
- no PyPI entry for manpage-writer, no "easy_install docutils-writer-
manpage" or similar
- also no macports package for manpage-writer / rst2man 

The wish therefore would be:
- Either switch back to something that is easily / directly available 
through package management on all major plattforms
- provide proper packages of manpage-writer in PyPI or at least some URL 
where to get it (which, of course, would be out of scope of Mercurial 
developement - but rather importent if building hg relies on rst2man)

Thanks,
Michael

----------
messages: 10095
nosy: mg, michael
priority: wish
status: unread
title: doc: rst2man not directly available all platforms
topic: doc, documentation

____________________________________________________
Mercurial issue tracker <mercurial-bugs at selenic.com>
<http://mercurial.selenic.com/bts/issue1746>
____________________________________________________