Re: misleading diff-hunk header

[Stefano Lattarini <stefano.lattarini@gmail.com>]

On 08/25/2012 02:56 PM, Tim Chase wrote:
> On 08/24/12 23:29, Junio C Hamano wrote:
>> Tim Chase <git@tim.thechases.com> 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.

You can find more information in the on-line documentation:

  <http://www.gnu.org/software/diffutils/manual/diffutils.html>

HTH,
  Stefano