threads / announce / 2936

[ANNOUNCE] GIT preformatted documentation available.

Subject: [ANNOUNCE] GIT preformatted documentation available.

## tl;dr

2 messages between Dec 27, 2005 and Dec 28, 2005.

replies: 1people: 2as markdown or json

Junio C Hamano· Dec 27, 2005, 08:49 UTC · lore

I was asked to provide pre-formatted man pages (and perhaps html pages), since the time of kernel developers are better spent on what they do best, rather than preparing the xmlto toolchain.

I was planning to do a tarball every time I do a "release", but that would mean it is no better than the current way --- you could extract manpages out of rpm anyway.

So instead, I'll do independent branches "html" and "man" in git.git repository to keep the preformatted documentation.

	$ mkdir git.man ; cd git.man
	$ git init-db
        $ ID=$(git fetch-pack -k git://git.kernel.org/pub/scm/git/git man)
        $ expr "$ID" : '\(.*\) .*' >.git/refs/heads/master
        $ cat .git/refs/heads/master >.git/refs/heads/origin
	$ git checkout; /bin/ls -aF
	./  ../  .git/	man1/  man7/
        $ echo >.git/remotes/origin <<\EOF
        URL: git://git.kernel.org/pub/scm/git/git
        Pull: man:origin
        EOF

Would set you up, and you can to keep them up-to-date, and install them like so:

	$ cd git.man
	$ git pull
	$ cp -a man1 man7 /usr/local/man/

The "html" branch is similar; it is a copy of what is shown at http://www.kernel.org/pub/software/scm/git/docs/.

This means if you clone from git.git repository, you would end up with something like this in .git/remotes/origin file:

	URL: git://git.kernel.org/pub/scm/git/git.git
        Pull: master:origin
        Pull: todo:todo
        Pull: html:html
        Pull: man:man
        Pull: pu:pu
        Pull: maint:maint

Typically, for the repository to track GIT itself, you would want to trim them like this:

	URL: git://git.kernel.org/pub/scm/git/git.git
        Pull: master:origin
        Pull: maint:maint
        Pull: +pu:pu
Adrien Beau· Dec 28, 2005, 16:51 UTC · re: Junio C Hamano · lore

Re: [ANNOUNCE] GIT preformatted documentation available.

On 12/27/05, Junio C Hamano <junkio@cox.net> wrote:
Show 11 quoted lines
>
> I was asked to provide pre-formatted man pages (and perhaps html
> pages), since the time of kernel developers are better spent on
> what they do best, rather than preparing the xmlto toolchain.
>
> I was planning to do a tarball every time I do a "release", but
> that would mean it is no better than the current way --- you
> could extract manpages out of rpm anyway.
>
> So instead, I'll do independent branches "html" and "man" in
> git.git repository to keep the preformatted documentation.

Having preformatted documentation is a great step forward, but it would be even better if we could have it without installing some weird RPM tool or a local copy of the Git repository -- not all my machines have that.

Besides, it's not very beginner- or newcomer-friendly. Grab the source; discover you need a complex toolchain to have manpages; maybe learn sometime later that "all you had to do" was get an RPM and explode some parts of it -- nah, it just doesn't feel right.

You're already generating five RPMs and two tarballs everytime you release a version, would it be much more taxing to generate a third tarball?

That said, those two new branches are neat. Thanks!

← back to recent threads