Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 5, 2023, 21:11 UTC
Message-ID: <xmqqcyxshizq.fsf@gitster.g>
In-Reply-To: <CAPig+cT63L2+XmDRKw4Pc+iDmUL+UFcyummOcOtS+3wYaNbFvg@mail.gmail.com>

Eric Sunshine <sunshine@sunshineco.com> writes:

Show 8 quoted lines

>> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
>> @@ -43,66 +43,74 @@ endif::git-diff[]
>> +-m::
>> +       Show diffs for merge commits in the default format. This is
>> +       similar to '--diff-merges=on' (which see) except `-m` will
>> +       produce no output unless `-p` is given as well.
>
> I'm having difficulty grasping the parenthetical "(which see)" comment.

I am, too. I know what it means when written in the more common Latin abbreviation (q.v.), but I suspect it may be rare to spell it in English like this. I found

https://writingcenter.unc.edu/tips-and-tools/latin-terms-and-abbreviations/

that starts its explanation with this:

     The abbreviation q.v. stands for quod vide, which translates
     literally as “which see,” although in practice it mea
     something more like “for which see elsewhere.

and it goes on to say:

     The reader is expected to know how to locate this information
     without further assistance. Since there is always the
     possibility that the reader won’t be able to find the
     information cited by q.v., it’s better to use a simple English
     phrase such as “for more on this topic, see pages 72-3” or
     “a detailed definition appears on page 16.” Such phrases are
     immediately comprehensible to the reader (who may not even know
     what q.v. means) and remove any ambiguity about where
     additional information is located.

which only applies halfway to this example, as with the text before it makes it very clear for readers that they need to learn about "--diff-merges=on". It is so clear to the point that the only effect "(which see)" here has is to waste bytes and confuses readers, I am afraid.