Subject: Re: [ANNOUNCE] Guilt v0.31

From: Michael J Gruber <[email-masked]>
Date: Tue, 09 Sep 2008 12:10:19 +0200

Junio C Hamano venit, vidit, dixit 08.09.2008 21:17:
> "Bert Wesarg" <[email-masked]> writes:
> 
>> I must admit, that I don't like these extra tarballs with docs. I
>> always expect, that the manpages are nicely installed if I type 'make
>> install' (or at least with a install-doc target). But I need to
>> download this extra package, and extract it to the right place, there
>> is no Makefile whatsoever. In case of git its really annoying, because
>> the help mechanism is relying on the manpages (i.e. git help <cmd> or
>> git <cmd> --help, but you know this).
> 
> There is no need to feel "it[']s really annoying", as install-doc from the
> tarball distribution works out of the box.
> 
> I used 1.6.0.1 in the demonstration below, but this is nothing new in that
> version but has been like this for quite some time (it is how sample RPMs
> binary packages are built, so the procedure ought to work):
> 
>     $ ls -1 /usr/bin/git ;# to show there is no other "git" on this box
>     ls: /usr/bin/git: No such file or directory
>     $ mkdir /var/tmp/16
>     $ cd /var/tmp/16
>     $ wget http://www.kernel.org/pub/software/scm/git/git-1.6.0.1.tar.gz
>     $ tar xf git-1.6.0.1.tar.gz
>     $ cd git-1.6.0.1
>     $ make prefix=/var/tmp/16test install install-doc
>     $ PATH=/var/tmp/16test/bin:/usr/bin:/bin
>     $ export PATH
>     $ unset MANPATH
>     $ git help cat-file | cat -s | tail -n 8
>     Reformatting git-cat-file(1), please wait...
>     DOCUMENTATION
>            Documentation by David Greaves, Junio C Hamano and the git-list
>            <[email-masked]>.
> 
>     GIT
>            Part of the git(1) suite
> 
>     Git 1.6.0.1                       09/08/2008                   GIT-CAT-FILE(1)
> 

This works because you have the full toolchain, especially xmlto.
asciidoc'ing directly to man (bypassing xmlto) may help some of us.

> The extra tarballs for documentation are also given as courtesy because
> they are supposed to be platform independent and some people do not want
> to generate them themselves (even though they could).
> 
> Either be thankful for the availability of tarballs, or ignore them and
> generate them yourself --- it's your choice.

He might want an install target which installs doc from the doc-tarball
or from the man- and html-branches. Be it a Makefile in those
convenience branches. I know it's just a tar or cpio away, of course. I
might look at a Makefile for the doc branches.

Michael