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

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

Jari Aalto <jari.aalto@cante.net> writes:

> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
> ---
>  Documentation/git-add.txt |   10 +++++-----
>  1 files changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index e67b7e8..71990c2 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -67,14 +67,14 @@ OPTIONS
>  --interactive::
>  	Add modified contents in the working tree interactively to
>  	the index. Optional path arguments may be supplied to limit
> -	operation to a subset of the working tree. See ``Interactive
> -	mode'' for details.
> +	operation to a subset of the working tree. See section
> +	``INTERACTIVE MODE'' for details.

Sorry, the change in this hunk does not make *any* sense to me.

It is not justified with your commit log message, I do not see why you
have to shout in all CAPS, and there is no such section in the
documentation.  But the "Interactive mode" section exists and is referred
to by the original.

>  -p::
>  --patch::
> -	Similar to Interactive mode but the initial command loop is
> -	bypassed and the 'patch' subcommand is invoked using each of
> -	the specified filepatterns before exiting.
> +	Run interactive patch command for each file on command line.
> +	See section INTERACTIVE MODE and patch subcommand for more
> +	information.

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.

If you assume that the reader is not familiar with "add -i", then the
above is not descriptive enough, but "Run interactive patch command" is
not an improvement either.  We would need a description of "what it is
used for" before "how it would look to you" (i.e.. my rewrite shown
above).

"What it is used for" would perhaps read like this.

	Review the difference between the index and the work tree, and add
	modified contents to the index interactively by choosing which
	patch hunks to use.