Stefano Lattarini <stefano.lattarini@xxxxxxxxx> writes:
> On 08/25/2012 02:56 PM, Tim Chase wrote:
>> On 08/24/12 23:29, Junio C Hamano wrote:
>>> Tim Chase <git@xxxxxxxxxxxxxxxxx> writes:
>>>> If the documented purpose of "diff -p" (and by proxy
>>>> diff.{type}.xfuncname) is to show the name of the *function*
>>>> containing the changed lines,....
>>>
>>> Yeah, the documentation is misleading, but I do not offhand think of
>>> a better phrasing. Perhaps you could send in a patch to improve it.
>>>
>>> How does GNU manual explain the option?
>>
>> Tersely. :-)
>>
>> -p --show-c-function
>> Show which C function each change is in.
>>
> That's in the manpage, which is basically just a copy of the output from
> "diff --help". In the texinfo manual (which is the real documentation),
> there are additional explanations, saying, among other things:
>
> To show in which functions differences occur for C and similar languages,
> you can use the --show-c-function (-p) option. This option automatically
> defaults to the context output format (see Context Format), with the
> default number of lines of context. You can override that number with
> -C lines elsewhere in the command line. You can override both the format
> and the number with -U lines elsewhere in the command line.
> The -p option is equivalent to -F '^[[:alpha:]$_]' if the unified format
> is specified, otherwise -c -F '^[[:alpha:]$_]' (see Specified Headings).
> GNU diff provides this option for the sake of convenience.
> ...
> The --show-function-line (-F) option finds the nearest unchanged line
> that precedes each hunk of differences and matches the given regular
> expression.
So in short, if we say "Show which function each change is in" in
the documentation, that is consistent with what GNU does and that is
described consistently with what GNU says, modulo that we obviously
do more than "C" via the diff.<driver>.xfuncname mechanism.
We already document diff.<driver>.xfuncname as determining "the hunk
header", and the documentation that is referred to (i.e. gitattributes)
shows the shape of a hunk in the "diff" output:
@@ -k,l +n,m @@ TEXT
This is called a 'hunk header'. The "TEXT" portion is by default a line
that begins with an alphabet, an underscore or a dollar sign; this
matches what GNU 'diff -p' output uses.
and then later says:
Then, you would define a "diff.tex.xfuncname" configuration to
specify a regular expression that matches a line that you would
want to appear as the hunk header "TEXT".
Honestly, I do not offhand see an obvious and possible room for vast
improvement over what we already have, so my RFH to Tim that appears
at the beginning of what you quoted from my previous message still
stands ;-).
Thanks.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html