Re: [PATCH] apply: clarify that index information is embedded, not the index itself

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

Alex Henrie <alexhenrie24@gmail.com> writes:

> Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
> ---
> The Spanish translation got this wrong.
> ---
>  Documentation/git-apply.txt | 2 +-
>  apply.c                     | 4 ++++
>  2 files changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
> index b9aa39000f..474be244ca 100644
> --- a/Documentation/git-apply.txt
> +++ b/Documentation/git-apply.txt
> @@ -92,7 +92,7 @@ OPTIONS
>  	with the `--reject` and the `--cached` options.
>  
>  --build-fake-ancestor=<file>::
> -	Newer 'git diff' output has embedded 'index information'
> +	Newer 'git diff' output has 'index information' embedded
>  	for each blob to help identify the original version that

Thanks.  

While we are looking at this paragraph, let me remind us that this
"Newer" refers to the output from "git diff" and friends newer than
ec1fcc16 ("Show original and resulting blob object info in diff
output.", 2005-10-07); it way outlived its freshness and we probably
should drop it.

> diff --git a/apply.c b/apply.c
> index f8a046a6a5..86f7cb3d88 100644
> --- a/apply.c
> +++ b/apply.c
> @@ -4987,6 +4987,10 @@ int apply_parse_options(int argc, const char **argv,
>  		OPT_BOOL('3', "3way", &state->threeway,
>  			 N_( "attempt three-way merge if a patch does not apply")),
>  		OPT_FILENAME(0, "build-fake-ancestor", &state->fake_ancestor,
> +			/*
> +			 * TRANSLATORS: Information about the index is embedded, not the
> +			 * index itself.
> +			 */

I am not sure if this helps much.  The term "index information" was
coined purely based on where this piece of info appears (i.e. on the
"index from..to" line of the diff output).  We use "object names on
the 'index' line of the patch" to build the temporary index to
perform --3way, and it is fair to say "object names are embedded on
the index line", but calling the information "index info embedded on
the index line" feels quite redundant.

It is too late for this cycle to touch the translatable strings, but
I think it is better to revamp any docs and messages that say
"embedded index information" soon after the next release.

>  			N_("build a temporary index based on embedded index information")),

Perhaps

	N_("build a temporary index using object names in the patch")

or something.

Notice I kept saying "object names" and not "blob object names"?
That is because we can show commit object name when the diff
involves a submodule.  We have a choice to make here. (1) strive to
technical correctness, somewhat sacrificing readability by avoiding
the word "blob", or (2) tell a white lie for the sake of simplicity
and pretend there is no submodule involved.  I actually think the
latter may be more appropriate here, in which case

	N_("build a temporary index using blobs recorded in the patch")

may be easier.  The documentation needs to match, but it already
pretends that there is no such thing as submodule ...

> +	Newer 'git diff' output has 'index information' embedded
>  	for each blob to help identify the original version that

... probably because the paragraph predates the invention of
the submodule mechanism.