Re: Git manuals

On Sun, Nov 19, 2006 at 06:59:52PM +0100, Petr Baudis wrote:

On Sun, Nov 19, 2006 at 06:50:40PM CET, J. Bruce Fields wrote:

quoted

In fact, I'm tempted to submit a patch that just assigns a chapter
number to everything under Documentation/, slaps a single table of
contents on the front, and calls the result "the git user's manual."

Of course, the moment people started trying to read the thing they'd
complain that it was a mess--some stuff referenced without being
introduced, other stuff introduced too many times.  But then over time
maybe that'd force us to mold it into some sort of logical sequence.

Sequencing isn't the only problem. A _manual_ is different from
_reference documentation_ in that it does not usually describe command
after command, but rather concept after concept. So instead of slamming
git-*-pack commands together, you have a section "Handling Packs" where
you try to coherently describe the commands together.

Your approach is fine for something you would call "Git Reference
Manual", but it is something really different from "The Git Book" or
"Git User's Manual".

Yeah, of course, but I wasn't actually thinking of the man pages so much
as:
	everyday.txt
	tutorial.txt
	tutorial-2.txt
	core-tutorial.txt
	howto/
	hooks.txt
	README
	glossary.txt

etc.