Re: misleading diff-hunk header

Stefano Lattarini [off-list ref] writes:

On 08/25/2012 02:56 PM, Tim Chase wrote:

quoted

On 08/24/12 23:29, Junio C Hamano wrote:

quoted

Tim Chase [off-list ref] writes:

quoted

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.