Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

Junio C Hamano [off-list ref] writes:

Sections that are common in all manual pages (e.g. NAME, SYNOPSIS,
DESCRIPTION, EXAMPLES, SEE ALSO) are often spelled in and referred to in
caps. 

Not just common ones. All sections that are top level heading are best
spelled out consistently. Examples can be found from the URL to
POSIX/Susv in my other post.

[I'll get back to the CAPS patch in anaother post if we can sort this out]

See http://www.kernel.org/pub/software/scm/git/docs/git-add.html#_interactive_mode
for what I mean.

I think the convention used in git's manual pages deviate from the
standard practise. We could make the git manual pages into line of:

- write all the first level headings in all caps: "HEADING LIKE THIS"
- write second level heading: start Upper-lower: "Heading like this"

Cf. rsync(1), ssh(1) etc. many pages prior git's existense.

quoted

quoted

I personally think fixing misworded phrase "initial command loop" would be
sufficient.  It should read "initial command menu".  Perhaps like this.

	Run ``add --interactive``, but bypass the initial command menu and
	directly jump to `patch` subcommand.  See ``Interactive mode'' for
	details.

It's still too technical. The 1st line should go right into business:

 	Patch each file on command line interactively. This is this is
 	the same as ``add --interactive``, but bypass the initial
 	command menu and directly jump to `patch` subcommand. See
 	``Interactive mode'' for details.

I do not think it is better than the original.

Your proposal that starts:

    ...but bypass the initial command menu

Mine:

    Patch each file on command line interactively

The first line should somehow strike immediately what the command does.
I would like to see a suggestion that has 'patch(ing)' somewhere at the
very first row. I hope we can find compromise.

Jari