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

From: Jari Aalto <jari.aalto@cante.net>
Date: Aug 30, 2009, 23:06 UTC
Message-ID: <87ab1gaol2.fsf@jondo.cante.net>
In-Reply-To: <7vskf954sr.fsf@alter.siamese.dyndns.org>

Junio C Hamano <gitster@pobox.com> 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.

Show 15 quoted lines

>>> 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