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

[Visuwesh <visuweshm@gmail.com>]

[வியாழன் அக்டோபர் 26, 2023] Po Lu wrote:

> Visuwesh <visuweshm@gmail.com> writes:
>
>> I find the new text is quite hard to understand, how about saying
>>
>>     Each handler function is called with the URL that matched it and one
>                                                         -------
>
> When was this matched?  You have excluded the text that indicates the
> event where this comparison takes place.

Oops, I excluded it because I was looking at the old text and writing
the new one and got confused.  FWIW, "it" is quite clear considering the
previous paragraph which says

     This variable is an alist between regexps against which URLs are
     matched and DND handler functions called on the dropping of
     matching URLs.

>>     of the symbols @code{copy}, @code{move}, @code{link}, @code{private}
>>     or @code{ask} identifying 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.
>
> I want to place emphasis on the new behavior, so it must come first in
> that paragraph.  But if there's anything else which you find ambiguous,
> please say so.

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".

> I've come to recognize that documentation should generally avoid words
> or collocations that betray indecision or uncertainty on the part of the
> writer (consider "by default" or "instead").  

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.

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.

While I enjoy increasing my vocabulary, it is not at all fun to keep
looking up words in the dictionary to understand a _manual_.  I humbly
ask you: Please use simple, common English words that everyone can
understand.

> The replacement for "by default" is to mention the general behavior
> first, followed by an account of each exception to it.  Words such as
> "instead" should be removed, since they are inserted to clarify the
> subject of a qualification, and become redundant once such
> qualifications are directly placed after their subjects.  The
> documentation produced is pither and less prey to interpretation.

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.