From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Visuwesh Newsgroups: gmane.emacs.devel Subject: Re: master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time Date: Thu, 26 Oct 2023 20:15:56 +0530 Message-ID: <87fs1x4f2z.fsf@gmail.com> References: <169832033169.28109.14749982523827239030@vcs2.savannah.gnu.org> <20231026113852.37241C09BEB@vcs2.savannah.gnu.org> <87jzr94jem.fsf@gmail.com> <87edhhzefl.fsf@yahoo.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="5384"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: emacs-devel@gnu.org To: Po Lu Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Oct 26 16:46:53 2023 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1qw1dN-0001EH-De for ged-emacs-devel@m.gmane-mx.org; Thu, 26 Oct 2023 16:46:53 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qw1co-0004RC-QZ; Thu, 26 Oct 2023 10:46:18 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qw1ce-0004Im-Ia for emacs-devel@gnu.org; Thu, 26 Oct 2023 10:46:08 -0400 Original-Received: from mail-pl1-x643.google.com ([2607:f8b0:4864:20::643]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qw1cX-0002Op-Hw for emacs-devel@gnu.org; Thu, 26 Oct 2023 10:46:08 -0400 Original-Received: by mail-pl1-x643.google.com with SMTP id d9443c01a7336-1c9b7c234a7so8461645ad.3 for ; Thu, 26 Oct 2023 07:46:00 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1698331560; x=1698936360; darn=gnu.org; h=content-transfer-encoding:mime-version:user-agent:message-id:date :references:in-reply-to:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=T4Lsi1kNW7j66fJbhsIIYQ2StSmu06r5fAzvrAp495Y=; b=FXkm+nkSn7eZRP4pRhfO3iauwxErPmH2YGtXpytzw5Uhmcl1/LeI5YvHW8dD974Xgp LyTtMGLZ1yzWz4oB84ZifiuA48KY4ta+hZsDj3N9wBnD1gFwwwc1sypjmBj6kHHMQonC j3Q0tpgq74WVF2hKlaA2LvZyb1k9OEnpkvIyFIfJqhcjpCcmjvzT9wU43lxgfbDw/dfX eLIdLs589VDfS7+/YEhCMXKsm3zr5KwGMtzOG9Rnt+nXgADK/usYxZWwfHK020Zeuv7I oT6wUBSLpWI1vC5A+/PtCNkMEnt+RmjHAn4xq6em2aeZK+MqvGz2MaY1dG3lEllsVb7m y6JA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1698331560; x=1698936360; h=content-transfer-encoding:mime-version:user-agent:message-id:date :references:in-reply-to:subject:cc:to:from:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=T4Lsi1kNW7j66fJbhsIIYQ2StSmu06r5fAzvrAp495Y=; b=fFrQpSoUQnmRIx0XltoGNhoGnHTLBpGAns2L351kHTZxhW7a0rCkcNNwizOs7EApT5 S8R1FJRZUjbu3jHht84zMmjephtGLStCmUvD9OfBtfQ4EdtXUZO/V6RQ4wiwNkemp0/M RB3SI8GfZNoM12yszGmlOp7ICTPsUAf5Sb+FZ073kbAPW4f1WBQaUufh7RWbvTzHq5wM yOI4wRZbSxY5yWWvlXNetSXtqisVT3Xyk1E9Cpr8lZcHWl4nu3sLTkS4Nrjnm5JKQa4O 591DO2BpnQhWwRs8IQ+6uWhlz5pcNDpd0/3UB3xQYAS8d+xGIxx1cHIOdc4i4mdwxxNt qYnw== X-Gm-Message-State: AOJu0YwRFSLjppW8tofXhTcUaTAdG/Hz6VxWRreUxBm2Y6Oi69rtgiOU EGE5BS5mufSUje/H3DAVxfU= X-Google-Smtp-Source: AGHT+IHK7Kf+BO5gExIIEV3xhx5mViCudoOVcyeQjD/SS3UVddfCYmKjxlUnsl/tCPecG+RiNsb/Bw== X-Received: by 2002:a17:903:2286:b0:1bd:da96:dc70 with SMTP id b6-20020a170903228600b001bdda96dc70mr20969156plh.49.1698331559567; Thu, 26 Oct 2023 07:45:59 -0700 (PDT) Original-Received: from localhost ([115.240.90.130]) by smtp.gmail.com with ESMTPSA id bv8-20020a632e08000000b00578b8fab907sm10633200pgb.73.2023.10.26.07.45.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 26 Oct 2023 07:45:59 -0700 (PDT) In-Reply-To: <87edhhzefl.fsf@yahoo.com> (Po Lu's message of "Thu, 26 Oct 2023 21:44:14 +0800") Received-SPF: pass client-ip=2607:f8b0:4864:20::643; envelope-from=visuweshm@gmail.com; helo=mail-pl1-x643.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:311912 Archived-At: [=E0=AE=B5=E0=AE=BF=E0=AE=AF=E0=AE=BE=E0=AE=B4=E0=AE=A9=E0=AF=8D =E0=AE=85= =E0=AE=95=E0=AF=8D=E0=AE=9F=E0=AF=8B=E0=AE=AA=E0=AE=B0=E0=AF=8D 26, 2023] P= o Lu wrote: > Visuwesh 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").=20=20 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 =E2=80=9Cfancy=E2=80=9D 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.