From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#55527: 28.1; Clearer abbrev docstrings Date: Fri, 20 May 2022 08:48:28 +0300 Message-ID: <837d6gdaab.fsf@gnu.org> References: <83bkvtcq38.fsf@gnu.org> <838rqxcnkk.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="39420"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 55527@debbugs.gnu.org To: Howard Melman Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri May 20 07:49:35 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1nrvW3-000AAV-EJ for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 20 May 2022 07:49:35 +0200 Original-Received: from localhost ([::1]:44140 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nrvW2-0000sp-0C for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 20 May 2022 01:49:34 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42626) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrvVa-0000sW-Er for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 01:49:08 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:43393) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nrvVW-0007Q6-09 for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 01:49:06 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nrvVV-0004VG-UX for bug-gnu-emacs@gnu.org; Fri, 20 May 2022 01:49:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 20 May 2022 05:49:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 55527 X-GNU-PR-Package: emacs Original-Received: via spool by 55527-submit@debbugs.gnu.org id=B55527.165302571817276 (code B ref 55527); Fri, 20 May 2022 05:49:01 +0000 Original-Received: (at 55527) by debbugs.gnu.org; 20 May 2022 05:48:38 +0000 Original-Received: from localhost ([127.0.0.1]:37290 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrvV8-0004Ua-GE for submit@debbugs.gnu.org; Fri, 20 May 2022 01:48:38 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:49278) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nrvV6-0004UM-Qz for 55527@debbugs.gnu.org; Fri, 20 May 2022 01:48:37 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:49058) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrvV1-0007Nf-Gq; Fri, 20 May 2022 01:48:31 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=Z0uFCuiVbA6NkaqNVD1G/e5BqXsKEbHkFS2od2v8Boo=; b=a1XmtDaBZ36R h2KOOVlSPxhHFGF8K7nekHPMkpCKeEgRRGJO/ocv8mC8xILv0n+qnMb3ocIkw8ZJ+zZTwSdOVIYNq czgIjDv+ofxsegtLMBPOSLMVXJOvfToIOcpmtuMpovy9u9xXfhpoINUFZ9Z2apatfiKwfWJDTm4Gq 2wb4oSORqR7Gsup8lPBLwRU9f33zjBsJNoRQPruBQ+uEwr2hOKjMwTEGPCNxeKkkQu8EAOLNfSKnk sLy5O4SP51iV+Ij39hUjEmKi02jao0FYtSq+xdEIY4425FGIXMBv4vQw4gnCDQBwx2ADUdBbWD9NC xY/e6YnIKJyz+vIG8dwpEw==; Original-Received: from [87.69.77.57] (port=3903 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nrvV0-0005az-HH; Fri, 20 May 2022 01:48:31 -0400 In-Reply-To: (message from Howard Melman on Thu, 19 May 2022 16:38:42 -0400) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:232691 Archived-At: > From: Howard Melman > Date: Thu, 19 May 2022 16:38:42 -0400 > > > If you add the expansion part, the line becomes too long, though: > > > > Define last word before point as expansion of a global (mode-independent) abbrev. > > I think you can loose the "mode-independent" part, as global > covers that pretty clearly, how about: > > Define last word before point as expansion of a global abbrev. No, "global" doesn't explain itself in this case, because we aren't talking about a minor mode. So I'd rather lose "a" or even replace "of a" with "for". We could also lose "last". > > It will be called, but by whom and when? > > Yes that was *my* point. The original says: > > Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK. > > which to me doesn't answer "by whom and when" Yes, it does: the abbrev you define will call HOOK at the time of the expansion. That's what the sentence says. > Define in TABLE an ABBREV and its EXPANSION and optionally its HOOK. "Define in TABLE" is awkward (or even incorrect) English. OTOH, "optionally" is redundant, so maybe if we lose it, we could reword the sentence to be more correct English-wise. > I don't think it's at all obvious how the original clauses > relate to each other (thankfully the full docstring is much > clearer) but as you brought up non-native english speakers I > would think the original is also difficult for them. The comparison is always relative, not absolute. And if the full doc string makes things clear, it's fine.