Re: [PATCH 2/2] diffcore-pickaxe doc: document -S and -G properly

From: Ramkumar Ramachandra <artagnon@gmail.com>
Date: Jun 2, 2013, 20:28 UTC
Message-ID: <CALkWK0=3SNJ0TFNaM18=DdMN5OQX4L=7-DO1x1U-ASqgFuDmhg@mail.gmail.com>
In-Reply-To: <7v7gicnv6o.fsf@alter.siamese.dyndns.org>

Junio C Hamano wrote:

>> Why do a poor-man's version of --pickaxe-all here, when the last
>> paragraph already does justice to this?
>
> The point of the first paragraph is to serve to help both:

My question pertains to whether or not the explanation of --pickaxe-all can wait till the last paragraph. You want to explain all the options in the first paragraph, but not --pickaxe-regex?

Show 14 quoted lines

>> While what you're saying is technically true, I think it is important
>> to explain the interaction between diffcore-pickaxe and
>> diffcore-rename as I have done.  Someone who wants to understand what
>> `git log -S` does will come to this page and read this section:
>> without reading diffcore-rename, she will have an incomplete picture;
>> what's the harm in explaining diffcore-rename in the context of
>> diffcore-pickaxe?
>
> This document is the most accurate _technical_ documentation of how
> the pipeline works (and it is not in section 1 of the manual set).
> If you want to improve end-user documentation by adding explanation
> for interactions between pipeline stages and also pathspec, I am all
> for it, but I think that belongs to the larger "git help diff", not
> "git help diffcore".

It's impossible to explain in the diff-options, because I do not have even have access to the word "filepair", and no diffcore-rename machinery to point to. I could attempt a vague approximation, but I do not think it's worth it. I'll remove it if you insist.