Re: Suggestion: doc restructuring

[Junio C Hamano <gitster@pobox.com>]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> So what I really would like is this: leave the plumbing pages as they are, 
> but enhance those pages that users (especially new ones) are likely to see 
> most often.

Regarding the original "do we want to ever teach plumbing to new users?"
issue, I suspect that, with sufficient enhancement to Porcelain, we might
be able to reach a point where end users can work without ever touching a
single plumbing command at all.

	Side note, that was why I suggested us to first think about use
	cases in our every day work that we still need to resort to the
	plumbing, so that we can identify what that enhancement would
	consist of.

When we reach that point, we might want to restructure the documentation
into two volumes.  One volume for end-users who exclusively use the stock
git Porcelain, and another that describes plumbing commands for Porcelain
writers.

Perhaps move the plumbing documentation to section 3; just like Perl has
DBI.3pm and friends there, /usr/share/man/man3/git-cat-file.3git will
describe what scripts can do with the command.