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

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

[Visuwesh]

[வியாழன் அக்டோபர் 26, 2023] Po Lu via Mailing list for Emacs changes wrote:

Thank you for working on this.

> @@ -4740,9 +4740,14 @@ This variable is an alist between regexps against which URLs are
>  matched and DND handler functions called on the dropping of matching
>  URLs.
>  
> -Each handler function is called with the URL that matched it and one
> -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 a handler function is a symbol whose @code{dnd-multiple-handler}
> +property (@pxref{Symbol Properties}) is set, then upon a drop it is
> +given a list of every URL that matches its regexp; absent this
> +property, it is called once for each of those URLs.  Following this
> +first argument is one of the symbols @code{copy}, @code{move},
> +@code{link}, @code{private} or @code{ask} identifying the action to be
> +taken.

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

?

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

[Po Lu]

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.

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

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

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

[Visuwesh]

[வியாழன் அக்டோபர் 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.

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

[Po Lu]

Visuwesh <visuweshm@gmail.com> writes:

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

The tense of the subsequent sentence's first clause renders this
ambiguous, at least to me.

> 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.  If it remains confusing to you, how about:

  "in the absence of this"

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

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

> 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,
and there are no replacements conveying the same meaning as "accorded",
in the sense of "granted or enabled by protocol or jurisprudence."

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

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

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.

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

[Visuwesh]

[வெள்ளி அக்டோபர் 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?

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

[Andreas Schwab]

On Okt 27 2023, Po Lu wrote:

> "Absent" has been a perfect synonym to the preposition of "without"
> since the mid-20th century.

A manual should not use colloquial language, it needs to be understood
by non-native English speakers.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

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

[Mattias Engdegård]

28 okt. 2023 kl. 13.37 skrev Andreas Schwab <schwab@linux-m68k.org>:

>> "Absent" has been a perfect synonym to the preposition of "without"
>> since the mid-20th century.
> 
> A manual should not use colloquial language, it needs to be understood
> by non-native English speakers.

Actually 'absent' as a preposition is rather formal than colloquial, but I agree it doesn't do a lot of good to the text here; just go with 'without'.