From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#67499: [PATCH] Add use cases of (fn) documentation facility. Date: Wed, 29 Nov 2023 23:29:58 +0000 Message-ID: <87edg89lsn.fsf@jeremybryant.net> References: <87il5mai0x.fsf@jeremybryant.net> <834jh47h99.fsf@gnu.org> Reply-To: Jeremy Bryant Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="6051"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 67499@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Nov 30 00:35:14 2023 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 1r8U5J-0001Gp-DE for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 30 Nov 2023 00:35:14 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r8U52-0004FJ-9c; Wed, 29 Nov 2023 18:34:56 -0500 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 1r8U51-0004FB-Ft for bug-gnu-emacs@gnu.org; Wed, 29 Nov 2023 18:34:55 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1r8U51-00050A-7p for bug-gnu-emacs@gnu.org; Wed, 29 Nov 2023 18:34:55 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1r8U58-0006nX-Fd for bug-gnu-emacs@gnu.org; Wed, 29 Nov 2023 18:35:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Jeremy Bryant Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 29 Nov 2023 23:35:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 67499 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 67499-submit@debbugs.gnu.org id=B67499.170130085526071 (code B ref 67499); Wed, 29 Nov 2023 23:35:02 +0000 Original-Received: (at 67499) by debbugs.gnu.org; 29 Nov 2023 23:34:15 +0000 Original-Received: from localhost ([127.0.0.1]:51721 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r8U4N-0006mQ-5O for submit@debbugs.gnu.org; Wed, 29 Nov 2023 18:34:15 -0500 Original-Received: from out-179.mta1.migadu.com ([2001:41d0:203:375::b3]:47204) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r8U4J-0006mH-Ux for 67499@debbugs.gnu.org; Wed, 29 Nov 2023 18:34:13 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1701300842; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=34SehDOXlaSE7Jqt+apvjZQbIUzWjy0VxD5527uCF0k=; b=T04nqb8ksPIami+AvVSY+P/4UNSkp9zt1hYOA1qMEcZei6FHv5+p3MNnDpWw5xEj6FaDIQ nwy6CLXEGxD5aGe+8lUMHlGwJndPB1V7tbu/vy+1k572esSbMuFB6i8/UNiGWEtnZ9ogir m5YiHj0/cS0rIncaRQ3qSNRcwUBHMiy63KpW2sofsefCXOJZKwU4fkdldDnE6n9TtK7Zv4 sxlufZregpMQ5/zEMvGh+NLmtleUIXu7JvLzYg54yp4ny9bX/vm6YXRNQjD/sCfzX9eR1G GfPdVHdk9cJOMIqKrqukqWGmMSgDioVqpjRsfqo4nvnBu1WVRxr20iaXoYIZMg== X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. In-reply-to: <834jh47h99.fsf@gnu.org> X-Migadu-Flow: FLOW_OUT 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-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:275262 Archived-At: --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> Date: Mon, 27 Nov 2023 23:30:33 +0000 >> From: Jeremy Bryant via "Bug reports for GNU Emacs, >> the Swiss army knife of text editors" >> >> I have written a proposed addition to the Elisp manual. In now-closed >> bug 66928, there was a discussion related to the use of \(fn) in doc >> strings, and I have drafted some examples to explain how this facility >> could be used. The addition is presented as @ifnottex... in order to >> reduce the cost of the printed manual. >> >> Feedback welcome on draft before I refine further, on conventions, section of >> manual, style etc. > > Thanks. > > I wonder whether we need this to be said in so many words. Can't we > instead just enumerate the uses, describing each one in a couple of > sentences, and format that as, say, an @itemize'd list? IOW, do we > really need to show an explicit example for each use? Examples are > useful when an example is worth a thousand words, which is not the > case here, I think. Understood, and substantially rewritten as attached, as an @itemize'd list. The reader can then use find-function at point in the info manual, to read the code. --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-Add-use-cases-of-fn-documentation-facility.patch >From 8ff1589630cb723857b6886c56ac836a333d69e5 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant Date: Mon, 27 Nov 2023 23:18:03 +0000 Subject: [PATCH] Add use cases of (fn) documentation facility. * doc/lispref/functions.texi (Function Documentation): Add examples --- doc/lispref/functions.texi | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index e646e7c8b0a..fe7ed78d568 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -533,6 +533,42 @@ Function Documentation compiler emit a warning message when it compiles Lisp programs which use the deprecated calling convention. +@ifnottex +In this section we outline examples of the use of the @code{(fn)} facility. + +@itemize @minus +@item Explaining @code{&rest} in a @code{defmacro}: + +@file{subr.el}: @code{lambda}. This is a canonical example where the +arguments are unclear, and the @code{(fn)} facility helps to spell out +the arglist @code{&rest}. + +@example +(defmacro lambda (&rest cdr) + "Return an anonymous function. (...) +\(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)"...) +@end example + +@item Explaining @code{&rest} in a @code{defun}, concretely: + +@file{keymap.el} : @code{define-keymap}. The single parameter +@code{&rest definitions} list is not clear, so the @code{fn} facility +explains it. + +@item Renaming parameters to give context in a @code{defalias}: + +@file{abbrev.el} : @code{(abbrev-get)}. Here @code{get}'s general argument of +@code{symbol} is renamed as @code{abbrev}. + +@item Naming list constituents in a required argument: + +@file{macroexp.el} : @code{macroexp--accumulate}. The argument of +@code{var+list}, which is more clearly described as @code{(var list)}. +@end itemize + +@end ifnottex + + @cindex computed documentation string @kindex :documentation Documentation strings are usually static, but occasionally it can be -- 2.42.0 --=-=-= Content-Type: text/plain > > A minor stylistic comments: > >> +In subr.el, the definition of lambda is as below, and the (fn) facility > ^^^^^^^ ^^^^^^ > File names should have the @file markup, and symbols and other code > fragments (like "&rest" and "defun") should have the @code markup. Added @file and @code for all applicable markups. In summary, the new compact text should help new contributors understand how the (fn) magic can be used. If it's not good to install, please let me know what to do. --=-=-=--