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.