Re: Shipping man pages?

[Mark Rosenstand <mark@borkware.net>]

On Thu, 2006-05-18 at 01:06 -0700, Junio C Hamano wrote:
> Tilman Sauerbeck <tilman@code-monkey.de> writes:
> 
> > atm, the git release tarballs don't contain man pages.
> 
> I ship *source* tarball.

Which is great for generating binaries and other things that are likely
to be incompatible across systems.

> I also happen to do RPM for people who do not want to build from
> the source (btw, I do that from pure inertia). In addition,
> preformatted manual pages and html docs are available from man
> and html branches of the git.git repository.
> 
> If you are building from the source, please build from the
> source.  Everything you need is right there.

But asciidoc is a royal PITA to package or install - it doesn't even
provide a Makefile: http://www.methods.co.nz/asciidoc/userguide.html#X38

Additionally it carries the whole docbook dependency chain with it.

> If you don't build from the source, please use whatever binary
> distribution available out there.  RPM happens to be available
> from kernel.org.  If you are on Debian/Ubuntu/Gentoo/others,
> please ask your distribution packager to include the manpages
> and html docs, if they don't already.

Even the packagers are likely to hate the unneccessary asciidoc
dependency. As a result some of the small distributions that don't have
the manpower to support 1000+ packages choose to ship git without the
man pages, which is a shame, IMO.

> Why does this have to come up so often, and everybody who asks
> for them never supplies the patch to do so?

Because it seems like a political decision rather than a technical one
(it's trivial to add the docs as a prerequisite for the dist target.)

> > Or maybe offer them in a separate tarball?
> 
> Things that are buildable from the source do not belong in the
> source tarball.  If somebody wants to do this as a patch, I can
> be talked into accepting it, but the build procedure should
> build a separate tarball (or two; one for man and another for
> woman^Whtml).

That would be great! I'd love to submit a patch, but I wouldn't be able
to test it, because I'd need asciidoc.