Re: master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time

[Visuwesh <visuweshm@gmail.com>]

[வெள்ளி அக்டோபர் 27, 2023] Po Lu wrote:

>> The problem is not with ambiguity but with too many clauses in a single
>> sentence which are hard to understand at a single passing.  IME, having
>> to read the same text in a manual multiple times because of its grammar
>> is tiring, especially so when you're reading it at the end of your day
>> when your energy is drained.
>>
>> Perhaps, the text written by you can be made better by removing the
>> semi-colon and turning the part after it into a separate sentence.
>> "absent this property..." sounds unnatural to me, I have not come across
>> such phrasing so I had to do a double-take to understand it.  A better
>> phrase might be "When this property is absent" or "When this property is
>> unset".
>
> "Absent" has been a perfect synonym to the preposition of "without"
> since the mid-20th century.  

Yet in my ~16 years of formal education in English medium, I have never
come across it.  It might be perfect but it is apparently not common in
every part of the world.

> If it remains confusing to you, how about:
>
>   "in the absence of this"

Yes, it is better and I hope you will also turn this clause into a
separate sentence decreasing the size of the original sentence.

> But observe that this is 4 words longer than "absent" or "without."

Compactness at the cost of clarity is pointless IMO.

>> I'd also kindly request you not use words in the manual that are
>> infrequently used since as a non-native speaker, I do not understand
>> them even after looking up the definition in the dictionary (GCIDE
>> here).  In the quoted text of your message, I don't fully understand
>> "collocations" despite looking at its definition in GCIDE, Wordnet 2006,
>> Wiktionary.  I suppose it is something akin to a phrase, or perhaps an
>> idiom.
>
> A collocation is a phrase comprising two words frequently placed
> together.

Thanks for the explanation.

>> In the same node of the manual: "too far removed" can be replaced with
>> "dissimilar" in the following paragraph.
>>
>>        Emacs does not take measures to accept data besides text and URLs,
>>     for the window system interfaces which enable this are too far removed
>>     from each other to abstract over consistently.  Nor are DND handlers
>>     accorded influence over the actions they are meant to take, as
>>     particular drag-and-drop protocols deny recipients such control.  The
>>     X11 drag-and-drop implementation rests on several underlying protocols
>>     that make use of selection transfer and share much in common, to which
>>     low level access is provided through the following functions and
>>     variables:
>>
>> Likewise, "accorded influence over" is far too “fancy” and the sentence
>> which contains it is not clear to me as a non-native speaker.
>
> This is unreasonable.  "Too far removed" is a widespread English phrase,

While I understood it perfectly fine, I truly wonder if it is common
enough for everyone to understand it.

> and there are no replacements conveying the same meaning as "accorded",
> in the sense of "granted or enabled by protocol or jurisprudence."

Why not use "granted" or "enabled" by the protocol then?  AFAIU, the
text here is conveying that the action to be performed by Emacs should
be within the grounds of what the protocol allows and not anything it
desires right?  If I am correct, this meaning does not come across from
the text unfortunately.  If I am wrong, the meaning is still not clear.

>> I don't know about others, but I find the pattern enforced by the use of
>> "by default" easier to understand since it gives the information in a
>> piecewise manner.  Perhaps, I am too used to reading a list of
>> exceptions after the rule as a chemistry major...
>>
>> Here's a second try at rewriting the originally quoted paragraph,
>>
>>     Each handler function is called with the URL that matches its
>>     regexp, and one of the symbols the symbols @code{copy}, @code{move},
>>     @code{link}, @code{private} or @code{ask} denoting the action to be
>>     taken.
>>
>>     @cindex dnd-multiple-handler, a symbol property
>>     If the handler function is a symbol whose property
>>     @code{dnd-multiple-handler} is non-@code{nil} (@pxref{Symbol
>>     Properties}), then it is given a list of every URL that matches its
>>     regexp as the first argument instead.
>
> `dnd-multiple-handler' must be mentioned first, for this is the behavior
> the documentation should prompt authors of new DND handlers to
> implement.

If that is your intent, symbol property is not the right interface for
this IMO.  In my modest experience in using Emacs, symbol properties act
like metadata or tell Emacs to handle it "specially" or "in an alternate
manner."  But here the "alternate manner" is the primary and the
recommended way to use it.  Is there not a way to do it that conveys
this message in a more substantial manner than the documentation?

> "Denote" in manuals sounds tawdry, though I can't put my finger on why.
> I think it's because that word is generally found in dictionaries, which
> manuals are not, and I never encounter it in prose.

How about "describe" then?  I think it is used elsewhere in docstrings
and in the manual.

> Furthermore, this text continues to omit any mention of the event _when_
> the function is called, which should be present in the same sentence
> illustrating how that is done.  I read it several times without such a
> mention, and each time felt something was off.
>
> Thanks.

How about

    At the time of drop, a handler function with a non-@code{nil} symbol
    property @code{dnd-multiple-handler} is called with a list of all
    URLs that match its regexp along with the action to be performed by
    the handler function described by one of the symbols @code{copy},
    @code{move}, @code{link}, @code{private}, or @code{ask}.  In the
    absence of the symbol property, the handler function is called for
    every matching URL instead of a list of matching URLs.

instead?