* Re: master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time [not found] ` <20231026113852.37241C09BEB@vcs2.savannah.gnu.org> @ 2023-10-26 13:12 ` Visuwesh 2023-10-26 13:44 ` Po Lu 0 siblings, 1 reply; 7+ messages in thread From: Visuwesh @ 2023-10-26 13:12 UTC (permalink / raw) To: emacs-devel; +Cc: Po Lu [வியாழன் அக்டோபர் 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. ? ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time 2023-10-26 13:12 ` master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time Visuwesh @ 2023-10-26 13:44 ` Po Lu 2023-10-26 14:45 ` Visuwesh 0 siblings, 1 reply; 7+ messages in thread From: Po Lu @ 2023-10-26 13:44 UTC (permalink / raw) To: Visuwesh; +Cc: emacs-devel 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. ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time 2023-10-26 13:44 ` Po Lu @ 2023-10-26 14:45 ` Visuwesh 2023-10-27 1:01 ` Po Lu 0 siblings, 1 reply; 7+ messages in thread From: Visuwesh @ 2023-10-26 14:45 UTC (permalink / raw) To: Po Lu; +Cc: emacs-devel [வியாழன் அக்டோபர் 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. ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time 2023-10-26 14:45 ` Visuwesh @ 2023-10-27 1:01 ` Po Lu 2023-10-28 11:20 ` Visuwesh 2023-10-28 11:37 ` Andreas Schwab 0 siblings, 2 replies; 7+ messages in thread From: Po Lu @ 2023-10-27 1:01 UTC (permalink / raw) To: Visuwesh; +Cc: emacs-devel 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. ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time 2023-10-27 1:01 ` Po Lu @ 2023-10-28 11:20 ` Visuwesh 2023-10-28 11:37 ` Andreas Schwab 1 sibling, 0 replies; 7+ messages in thread From: Visuwesh @ 2023-10-28 11:20 UTC (permalink / raw) To: Po Lu; +Cc: emacs-devel [வெள்ளி அக்டோபர் 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? ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time 2023-10-27 1:01 ` Po Lu 2023-10-28 11:20 ` Visuwesh @ 2023-10-28 11:37 ` Andreas Schwab 2023-10-28 11:49 ` Mattias Engdegård 1 sibling, 1 reply; 7+ messages in thread From: Andreas Schwab @ 2023-10-28 11:37 UTC (permalink / raw) To: Po Lu; +Cc: Visuwesh, emacs-devel 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." ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time 2023-10-28 11:37 ` Andreas Schwab @ 2023-10-28 11:49 ` Mattias Engdegård 0 siblings, 0 replies; 7+ messages in thread From: Mattias Engdegård @ 2023-10-28 11:49 UTC (permalink / raw) To: Andreas Schwab; +Cc: Po Lu, Visuwesh, emacs-devel 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'. ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2023-10-28 11:49 UTC | newest] Thread overview: 7+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <169832033169.28109.14749982523827239030@vcs2.savannah.gnu.org> [not found] ` <20231026113852.37241C09BEB@vcs2.savannah.gnu.org> 2023-10-26 13:12 ` master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time Visuwesh 2023-10-26 13:44 ` Po Lu 2023-10-26 14:45 ` Visuwesh 2023-10-27 1:01 ` Po Lu 2023-10-28 11:20 ` Visuwesh 2023-10-28 11:37 ` Andreas Schwab 2023-10-28 11:49 ` Mattias Engdegård
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.