From unknown Fri Jun 20 07:24:24 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#67499 <67499@debbugs.gnu.org> To: bug#67499 <67499@debbugs.gnu.org> Subject: Status: [PATCH] Add use cases of (fn) documentation facility. Reply-To: bug#67499 <67499@debbugs.gnu.org> Date: Fri, 20 Jun 2025 14:24:24 +0000 retitle 67499 [PATCH] Add use cases of (fn) documentation facility. reassign 67499 emacs submitter 67499 Jeremy Bryant severity 67499 normal tag 67499 patch thanks From debbugs-submit-bounces@debbugs.gnu.org Mon Nov 27 18:33:42 2023 Received: (at submit) by debbugs.gnu.org; 27 Nov 2023 23:33:42 +0000 Received: from localhost ([127.0.0.1]:45068 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r7l6j-0003uX-Kx for submit@debbugs.gnu.org; Mon, 27 Nov 2023 18:33:42 -0500 Received: from lists.gnu.org ([2001:470:142::17]:35416) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r7l6h-0003uJ-Mm for submit@debbugs.gnu.org; Mon, 27 Nov 2023 18:33:40 -0500 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 1r7l6V-0004Dg-FZ for bug-gnu-emacs@gnu.org; Mon, 27 Nov 2023 18:33:27 -0500 Received: from out-187.mta1.migadu.com ([95.215.58.187]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r7l6S-00023C-Mt for bug-gnu-emacs@gnu.org; Mon, 27 Nov 2023 18:33:27 -0500 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1701128001; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type; bh=IlQvr6Zchc9n5LnMyYDJNLsYdVwyunVIEbfgYhvFL2s=; b=J3uEMrFOBO8yIi7c5ciXc6NyJIL+iuLCkq0DQAQ/OPvAYFmlAriZgZxIa7u2+rp/CrUbbw QICmJWk7+txaf+eaNMnGgkmztyKN9VoJOTh5OExd5TkbygrGzkitFelZc1WrIFhWQ3mcJ2 2bc0YlFm17ir/tDqosYbRdOZmUBp+3jbjO+ngjVKEton7oaQq7aRldCz3G24zojlNNIwUV ufCgrDddBr1v4yunyu+wlmC3hJtTrqqZWFYJrAM9yuTqpZV7vyXVv5SwhvUwtuUSqc+9q/ z1gVlabwr8QZf70wcfB3fum4Hvjr6fJlFhJCp/gCN2kq1vMMu9m1b5cxJajT6g== From: Jeremy Bryant To: bug-gnu-emacs@gnu.org Subject: [PATCH] Add use cases of (fn) documentation facility. Date: Mon, 27 Nov 2023 23:30:33 +0000 Message-ID: <87il5mai0x.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=95.215.58.187; envelope-from=jb@jeremybryant.net; helo=out-187.mta1.migadu.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, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) --=-=-= Content-Type: text/plain Tags: patch 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. > Interesting, thank you > Perhaps it would be of interest to add some text to the elisp manual in > (elisp) Function Documentation > Are there any conventions for manual additions? > in particular to keep the number of printed pages limited is there a way > to say 'don't print this node'? > thanks > Jeremy > Stefan Monnier writes: > >> One question, the elisp manual mentions that the \(fn ARGLIST) facility > >> is particularly useful for macros. > >> > >> Why would we use this for defuns? > > > > We use it for some defuns where ELisp's arglist functionality is not > > refined enough to express the intention of the programmer. > > For example, the "real" arglist may be > > > > name args &optional docstring &rest body > > > > but the intended arglist is > > > > name args [docstring] &rest body > > > > i.e. if `docstring` is not a string it's taken as the first instruction > > of `body`. > > > > > > Stefan --=-=-= Content-Type: text/patch Content-Disposition: attachment; filename=0001-Add-use-cases-of-fn-documentation-facility.patch >From 34d0e7b4a6f15769d7b32dc16e3f283f947069ab 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 | 93 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index e646e7c8b0a..92972d070ee 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -533,6 +533,99 @@ Function Documentation compiler emit a warning message when it compiles Lisp programs which use the deprecated calling convention. + +@c We use it for some defuns where ELisp's arglist functionality is not +@c refined enough to express the intention of the programmer. +@c For example, the "real" arglist may be + +@c name args &optional docstring &rest body + +@c but the intended arglist is + +@c name args [docstring] &rest body + +@c i.e. if `docstring` is not a string it's taken as the first instruction +@c of `body`. + +@ifnottex +In this section we outline examples of the use of the (fn) facility. + +Example with defmacro: +Here is a canonical example where arguments are unclear. +In subr.el, the definition of lambda is as below, and the (fn) facility +helps to spell out the arglist &rest. +@example +(defmacro lambda (&rest cdr) + "Return an anonymous function. +\(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)" + ) +@end example + +Similar example with defun: +define-keymap in keymap.el +The &rest definitions list is not clear, so the fn facility explains it. +@example +(defun define-keymap (&rest definitions) + "Create a new keymap and define KEY/DEFINITION pairs as key bindings. +Return the new keymap. +... +\(fn &key FULL PARENT SUPPRESS NAME PREFIX KEYMAP &rest [KEY DEFINITION]...)" +@end example + + +Example with defmacro of a required argument which gets renamed: +In macroexp.el, the macro @code{macroexp--accumulate}, has a first +argument of @code{var+list}, which is more clearly described to the +user as @code{(var list)}. Thus the arguments are clarified. +See example below: +@example +(defmacro macroexp--accumulate (var+list &rest body) + "Return a list of the results of evaluating BODY for each element of LIST. +Evaluate BODY with VAR bound to each `car' from LIST, in turn. +Return a list of the values of the final form in BODY. +The list structure of the result will share as much with LIST as +possible (for instance, when BODY just returns VAR unchanged, the +result will be eq to LIST). + +\(fn (VAR LIST) BODY...)" + (declare (indent 1)) + (let ((var (car var+list)) + (list (cadr var+list)) +...))) +@end example + +Example with defalias: +Example of abbrev-get in abbrev.el: +In this example, the general get facility to get the value of a +symbol's property, is better described as getting the relevant +abbrev's property value. +@example +(defalias 'abbrev-get 'get + "Get the property PROP of abbrev ABBREV +See `define-abbrev' for the effect of some special properties. + +\(fn ABBREV PROP)") +@end example + +Similar example of cl--defalias in cl-lib.el: +In this example, the arguments are the same, but for list they are called +OBJECTS, and for cl-values they are called VALUES. + +@example +(cl--defalias 'cl-values #'list + "Return multiple values, Common Lisp style. +The arguments of `cl-values' are the values +that the containing function should return. + +\(fn &rest VALUES)") +@end example + + +% See (elisp) Autoload for a mention of \fn to reference. + +@end ifnottex + + @cindex computed documentation string @kindex :documentation Documentation strings are usually static, but occasionally it can be -- 2.42.0 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Wed Nov 29 09:43:09 2023 Received: (at 67499) by debbugs.gnu.org; 29 Nov 2023 14:43:09 +0000 Received: from localhost ([127.0.0.1]:49267 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r8LmO-0002yo-LE for submit@debbugs.gnu.org; Wed, 29 Nov 2023 09:43:08 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:59110) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r8LmM-0002yJ-9g for 67499@debbugs.gnu.org; Wed, 29 Nov 2023 09:43:06 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r8Lm8-00051c-Q2; Wed, 29 Nov 2023 09:42:52 -0500 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=NjI6MGSAJxzUtxFECzrNaEbKN5THomlVHKtJFTGP7uU=; b=n55CDsm5oONg T6pA0t1gPEHHC+chxKrvhmgh9COTGoEhfj91nA96H41u2QeHEH8jMzaw/SC9FCRQdpfMT/6UawJ6m CpndsVZP/KGlr31iLrhOcWV4Sa8t0HG3zbeaftoqAZn/EqS4iON3BUH7kB1c/iJf/JY0WgFSZ4w4N pEQ6lAzdLk3W+3EbkfUzSTcQL5QVyoX0eFW1TBby7wkWl9IgO0hpdEkb4dB/pNed6yymeAJhIWyW1 7O1D9Gvzee0nB04kR0ppDkHYwc2WV5lcRb60ETeHn/yNvBYl31C7BOSsMhA30rrhRGvv1/sOK5Ojf /BkjDwpSqT0V4B7GDS4EuQ==; Date: Wed, 29 Nov 2023 16:42:42 +0200 Message-Id: <834jh47h99.fsf@gnu.org> From: Eli Zaretskii To: Jeremy Bryant In-Reply-To: <87il5mai0x.fsf@jeremybryant.net> (bug-gnu-emacs@gnu.org) Subject: Re: bug#67499: [PATCH] Add use cases of (fn) documentation facility. References: <87il5mai0x.fsf@jeremybryant.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 67499 Cc: 67499@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > 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. 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. From debbugs-submit-bounces@debbugs.gnu.org Wed Nov 29 18:34:15 2023 Received: (at 67499) by debbugs.gnu.org; 29 Nov 2023 23:34:15 +0000 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 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 References: <87il5mai0x.fsf@jeremybryant.net> <834jh47h99.fsf@gnu.org> 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. From: Jeremy Bryant To: Eli Zaretskii Subject: Re: bug#67499: [PATCH] Add use cases of (fn) documentation facility. Date: Wed, 29 Nov 2023 23:29:58 +0000 In-reply-to: <834jh47h99.fsf@gnu.org> Message-ID: <87edg89lsn.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 67499 Cc: 67499@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= 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. --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Sat Dec 02 08:44:54 2023 Received: (at 67499) by debbugs.gnu.org; 2 Dec 2023 13:44:54 +0000 Received: from localhost ([127.0.0.1]:56909 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r9QIf-0007c0-VG for submit@debbugs.gnu.org; Sat, 02 Dec 2023 08:44:54 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:47718) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r9QIe-0007bm-Ex for 67499@debbugs.gnu.org; Sat, 02 Dec 2023 08:44:53 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r9QIP-0001H3-D4; Sat, 02 Dec 2023 08:44:37 -0500 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=yfdj5aA2cF7zHWqfx/K6WLGpR1SpwuQ2vlcyJFHcCZE=; b=Uakw+xmGTe4L QfGmJ2RJITFipvNhXACIEDWIo1th1sPmis0BxDmDQDmM0xVlLQGw/AN01EmjEhEz7hIoiY+6oF5WU oZqUt199yuiTC2FevSBmxTDm2fUYzcxWotgWZ8jqkahIFo4o3m5ZQU/oMXtOMvCQZ5Yqu+WHRz9Za 1xiB7Syef7dc91mz9bJSPlmjqF9zQcWeYyqDLGbL1kMf5Zz0wXYpVanHSGwI2IzTtTzj1UoO6ZGUq 74fFjNW+xX9e8jkdmKfGAsruT9Z/ImSAJmdxHuWu//Q7KbuUgcTvmHsRxmQIuPAVHOhVea4thGQbf zuKR4qeKQx04aACVlbrjaw==; Date: Sat, 02 Dec 2023 15:44:35 +0200 Message-Id: <83bkb890sc.fsf@gnu.org> From: Eli Zaretskii To: Jeremy Bryant In-Reply-To: <87edg89lsn.fsf@jeremybryant.net> (message from Jeremy Bryant on Wed, 29 Nov 2023 23:29:58 +0000) Subject: Re: bug#67499: [PATCH] Add use cases of (fn) documentation facility. References: <87il5mai0x.fsf@jeremybryant.net> <834jh47h99.fsf@gnu.org> <87edg89lsn.fsf@jeremybryant.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 67499 Cc: 67499@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Jeremy Bryant > Cc: 67499@debbugs.gnu.org > Date: Wed, 29 Nov 2023 23:29:58 +0000 > > > Eli Zaretskii writes: > > > 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. Thanks. I actually had in mind an even shorter variant: The @code{(fn)} feature is typically used in the following situations: @itemize @minus @item To spell out arguments and their purposes in a macro or a function. Example: @example (defmacro lambda (&rest cdr) "@dots{} \(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)"@dots{}) @end example @item To provide a more detailed description and names of arguments. Example: @example (defmacro macroexp--accumulate (var+list &rest body) "@dots{} \(fn (VAR LIST) BODY@dots{})" (declare (indent 1)) (let ((var (car var+list)) (list (cadr var+list)) @dots{}))) @end example @item To better explain the purpose of a @code{defalias}. Example: @example (defalias 'abbrev-get 'get "@dots{} \(fn ABBREV PROP)") @end example WDYT? > The reader can then use find-function at point in the info manual, to > read the code. We don't include pointers to our sources in the manual, except in very rare cases. I'm not sure we need to do it here. One disadvantage of having pointers to files is that we need to keep the pointers up-to-date as development continues. Thanks. From debbugs-submit-bounces@debbugs.gnu.org Sun Dec 03 16:39:54 2023 Received: (at 67499) by debbugs.gnu.org; 3 Dec 2023 21:39:54 +0000 Received: from localhost ([127.0.0.1]:32890 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r9uBu-0008SC-2L for submit@debbugs.gnu.org; Sun, 03 Dec 2023 16:39:54 -0500 Received: from out-184.mta1.migadu.com ([2001:41d0:203:375::b8]:37250) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r9uBp-0008S2-U3 for 67499@debbugs.gnu.org; Sun, 03 Dec 2023 16:39:52 -0500 References: <87il5mai0x.fsf@jeremybryant.net> <834jh47h99.fsf@gnu.org> <87edg89lsn.fsf@jeremybryant.net> <83bkb890sc.fsf@gnu.org> DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1701639578; 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=qE7TJojgj+QnMHC5g77iESzCDyYj56RjaX5a8TSTcHc=; b=pDfxUyAzEFENgFSP4n7WKK3FeZGMBEy1JPYBdq5IKNs1OslHLALZfYW7L6x3t8b9xkM4w0 yB+lDXdo4rCgOxR7XC4Fm3LDhLMKEOzWYH0nzO1BN3MTN5X7ukJtkeC0vdNPr+A/OwloPd nJX6c71f2QkuMA8Wg+5gg9I8KMMNazyFJgMsmPvUtzb0ptlWd6OFEOqeVrZK3HndhQzbcX BXgROrQGnKTKr+id+GImZbjnrsIoeLUs8iJdA/TcyN7hunfOn1iAVJkQcroURTOXXYdues ZaePAQguLeNMmFiCtCgZpHRepQjhtOYfjgsJznvvXUmTy+Mytj+DLSsNzkrYcA== X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. From: Jeremy Bryant To: Eli Zaretskii Subject: Re: bug#67499: [PATCH] Add use cases of (fn) documentation facility. Date: Sun, 03 Dec 2023 21:35:38 +0000 In-reply-to: <83bkb890sc.fsf@gnu.org> Message-ID: <871qc39d9k.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 67499 Cc: 67499@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-Add-use-cases-of-fn-documentation-facility.patch >From 3f427ea7e437a83b5e62121032d0352abf6b4bd8 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant Date: Sun, 3 Dec 2023 21:32:01 +0000 Subject: [PATCH] Add use cases of (fn) documentation facility. * doc/lispref/functions.texi (Function Documentation): Add examples Co-authored-by: Eli Zaretskii --- doc/lispref/functions.texi | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index e646e7c8b0a..34a568b728e 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -533,6 +533,39 @@ Function Documentation compiler emit a warning message when it compiles Lisp programs which use the deprecated calling convention. +@ifnottex +The @code{(fn)} feature is typically used in the following situations: + +@itemize @minus +@item To spell out arguments and their purposes in a macro or a function. Example: + +@example +(defmacro lambda (&rest cdr) + "@dots{} +\(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)"@dots{}) +@end example + +@item To provide a more detailed description and names of arguments. Example: + +@example +(defmacro macroexp--accumulate (var+list &rest body) + "@dots{} +\(fn (VAR LIST) BODY@dots{})" + (declare (indent 1)) + (let ((var (car var+list)) + (list (cadr var+list)) +@dots{}))) +@end example + +@item To better explain the purpose of a @code{defalias}. Example: + +@example +(defalias 'abbrev-get 'get + "@dots{} +\(fn ABBREV PROP)") +@end example +@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 > > Thanks. I actually had in mind an even shorter variant: > > The @code{(fn)} feature is typically used in the following situations: > > @itemize @minus > @item To spell out arguments and their purposes in a macro or a > function. Example: > > @example > (defmacro lambda (&rest cdr) > "@dots{} > \(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)"@dots{}) > @end example > > @item To provide a more detailed description and names of arguments. > Example: > > @example > (defmacro macroexp--accumulate (var+list &rest body) > "@dots{} > \(fn (VAR LIST) BODY@dots{})" > (declare (indent 1)) > (let ((var (car var+list)) > (list (cadr var+list)) > @dots{}))) > @end example > > @item To better explain the purpose of a @code{defalias}. Example: > > @example > (defalias 'abbrev-get 'get > "@dots{} > \(fn ABBREV PROP)") > @end example > > WDYT? > Agree this is a more readable version of my initial attempts. The only thing that is not clear in my mind is the use of the @ifnottex. I have left it in the attached patch, as I understand we are trying to reduce the size of the printed manual? I have a 2-volume Elisp manual, which is out of date as the current ones don't seem to be printed. I have also added a line to the commit message which seems appropriate here given the rewrites: Co-authored-by: Eli Zaretskii If this is all suitable to install I agree to close the original bug. --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Tue Dec 12 17:19:29 2023 Received: (at 67499) by debbugs.gnu.org; 12 Dec 2023 22:19:29 +0000 Received: from localhost ([127.0.0.1]:57864 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rDB68-0002jo-Ql for submit@debbugs.gnu.org; Tue, 12 Dec 2023 17:19:29 -0500 Received: from out-172.mta0.migadu.com ([91.218.175.172]:14804) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rDB66-0002jf-AH for 67499@debbugs.gnu.org; Tue, 12 Dec 2023 17:19:27 -0500 References: <87il5mai0x.fsf@jeremybryant.net> <834jh47h99.fsf@gnu.org> <87edg89lsn.fsf@jeremybryant.net> <83bkb890sc.fsf@gnu.org> <871qc39d9k.fsf@jeremybryant.net> DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1702419549; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: references:references; bh=DzLLBSMQvnScVJXdHUw9YPAfDn7LoN3XkiQH5eTEsMk=; b=HUW3CkiLttAZE527986EQPRoe82Y+q+5WjyBrprXqwYR5h19uMYBIaGVRgwsAh8okJhLwo TkANJJDAP6cLigVyfFVABt+wVUAQuxFPFi6uP1F/0fZdTQpmHZInwDff4Gr/YX85vm5n1/ +Y2trBcQYGHj5VLt1M/48ZfkkSk3zjIOs67InvIzltS1tiC7f9qV+i74O39ZVa/tP0qFao fIby3QW+YC9ElsQedXTC82uLfz5iKyBesVWJy7F6IQUpWTBRIeaWSS/PWwJ4mvIr3eNoXZ H5/nQzynDBcL5r6PIC6asLOSiULzE9LCUZVnATrFJYov5btGsDZ7KDf2amvnlA== X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. From: Jeremy Bryant To: 67499@debbugs.gnu.org, Eli Zaretskii Subject: Fwd: bug#67499: [PATCH] Add use cases of (fn) documentation facility. Date: Tue, 12 Dec 2023 22:15:59 +0000 Message-ID: <8734w783oj.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 67499 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/plain Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of text editors" writes: > [1. text/x-diff; 0001-Add-use-cases-of-fn-documentation-facility.patch]... > > >> >> Thanks. I actually had in mind an even shorter variant: >> >> The @code{(fn)} feature is typically used in the following situations: >> >> @itemize @minus >> @item To spell out arguments and their purposes in a macro or a >> function. Example: >> >> @example >> (defmacro lambda (&rest cdr) >> "@dots{} >> \(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)"@dots{}) >> @end example >> >> @item To provide a more detailed description and names of arguments. >> Example: >> >> @example >> (defmacro macroexp--accumulate (var+list &rest body) >> "@dots{} >> \(fn (VAR LIST) BODY@dots{})" >> (declare (indent 1)) >> (let ((var (car var+list)) >> (list (cadr var+list)) >> @dots{}))) >> @end example >> >> @item To better explain the purpose of a @code{defalias}. Example: >> >> @example >> (defalias 'abbrev-get 'get >> "@dots{} >> \(fn ABBREV PROP)") >> @end example >> >> WDYT? >> > > Agree this is a more readable version of my initial attempts. > > The only thing that is not clear in my mind is the use of the @ifnottex. > I have left it in the attached patch, as I understand we are trying to > reduce the size of the printed manual? > > I have a 2-volume Elisp manual, which is out of date as the current ones > don't seem to be printed. > > I have also added a line to the commit message which seems appropriate > here given the rewrites: > Co-authored-by: Eli Zaretskii > > If this is all suitable to install I agree to close the original bug. Eli, Kindly let me know if the attached patch is good to install or if anything else is needed to work on for this bug report? Apologies if it's too soon to follow-up, as a newer contributor I do not yet have a good sense of timing on these things. Best, Jeremy --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-Add-use-cases-of-fn-documentation-facility.patch Content-Description: 0001-Add-use-cases-of-fn-documentation-facility.patch >From 3f427ea7e437a83b5e62121032d0352abf6b4bd8 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant Date: Sun, 3 Dec 2023 21:32:01 +0000 Subject: [PATCH] Add use cases of (fn) documentation facility. * doc/lispref/functions.texi (Function Documentation): Add examples Co-authored-by: Eli Zaretskii --- doc/lispref/functions.texi | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index e646e7c8b0a..34a568b728e 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -533,6 +533,39 @@ Function Documentation compiler emit a warning message when it compiles Lisp programs which use the deprecated calling convention. +@ifnottex +The @code{(fn)} feature is typically used in the following situations: + +@itemize @minus +@item To spell out arguments and their purposes in a macro or a function. Example: + +@example +(defmacro lambda (&rest cdr) + "@dots{} +\(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)"@dots{}) +@end example + +@item To provide a more detailed description and names of arguments. Example: + +@example +(defmacro macroexp--accumulate (var+list &rest body) + "@dots{} +\(fn (VAR LIST) BODY@dots{})" + (declare (indent 1)) + (let ((var (car var+list)) + (list (cadr var+list)) +@dots{}))) +@end example + +@item To better explain the purpose of a @code{defalias}. Example: + +@example +(defalias 'abbrev-get 'get + "@dots{} +\(fn ABBREV PROP)") +@end example +@end ifnottex + @cindex computed documentation string @kindex :documentation Documentation strings are usually static, but occasionally it can be -- 2.42.0 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Fri Dec 15 08:51:03 2023 Received: (at 67499) by debbugs.gnu.org; 15 Dec 2023 13:51:03 +0000 Received: from localhost ([127.0.0.1]:51778 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rE8al-0001Ba-GK for submit@debbugs.gnu.org; Fri, 15 Dec 2023 08:51:03 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:45106) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rE8ak-0001B4-3J for 67499@debbugs.gnu.org; Fri, 15 Dec 2023 08:51:02 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rE8ae-0000cc-Ra; Fri, 15 Dec 2023 08:50:56 -0500 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=qzka+iWx3N+U/vr9Lc1/pqMI8u1FBfpGgRb1VGbq8gI=; b=rsJ/hKKu3P82 ETSc7f/FE5UnLV8bqOxkJSe+sdDAxkPfuVDD2VbTskbn4RnbYkKXT1D1Wiu0AULAgLyQLGE41g8SQ ijcVyUmWIaZycuoLTmhbnJIYXsAjTRlQ+weQOIxPZdTjr3e8DBkIeASPyDSRu2QYO7QTWV0voAcTs tROUJDo+TrsxAlPr5JrNgsuA1ohfRksNrETuaf2M+0tvw7swPPVpVsRErQ6aSQOlNtTqPAH2RBJz+ TIwaojIwQO/lZP19P5kE+M/TOG+S+3bvVlmep5P4o7ZwCMJ9RDBTOfJ/QYJFHpUnM3ISRrUqBpxin +U4YnP6W+ROCpyXQXBkxHg==; Date: Fri, 15 Dec 2023 15:50:57 +0200 Message-Id: <83ttojo9q6.fsf@gnu.org> From: Eli Zaretskii To: Jeremy Bryant In-Reply-To: <8734w783oj.fsf@jeremybryant.net> (message from Jeremy Bryant on Tue, 12 Dec 2023 22:15:59 +0000) Subject: Re: Fwd: bug#67499: [PATCH] Add use cases of (fn) documentation facility. References: <87il5mai0x.fsf@jeremybryant.net> <834jh47h99.fsf@gnu.org> <87edg89lsn.fsf@jeremybryant.net> <83bkb890sc.fsf@gnu.org> <871qc39d9k.fsf@jeremybryant.net> <8734w783oj.fsf@jeremybryant.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 67499 Cc: 67499@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Jeremy Bryant > Date: Tue, 12 Dec 2023 22:15:59 +0000 > > Apologies if it's too soon to follow-up, as a newer contributor I do > not yet have a good sense of timing on these things. Usually two weeks with no progress are a good reason for a ping. I will get to this soon. From debbugs-submit-bounces@debbugs.gnu.org Sat Dec 16 07:58:52 2023 Received: (at 67499-done) by debbugs.gnu.org; 16 Dec 2023 12:58:52 +0000 Received: from localhost ([127.0.0.1]:54179 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rEUFo-0007Nk-IS for submit@debbugs.gnu.org; Sat, 16 Dec 2023 07:58:52 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:50144) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rEUFm-0007NY-T7 for 67499-done@debbugs.gnu.org; Sat, 16 Dec 2023 07:58:51 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rEUFh-0001iq-0T; Sat, 16 Dec 2023 07:58:45 -0500 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=cF3iWxXlxf++3P5Dr35oKMUhfSNCi1/vP7thJDDherk=; b=GILG/t8WrAgM PqEFhAxp3k0S+VzpU+vugfINZ0IWmOlw2KXIOl7HYYBcusj82ibEk2iQguYW2E+hsIBX0RFwoj3jQ i+x4MM4qKQ3Q2N6//2pxqh0X1P4ZV67pg8BO2hR1HcL/2ykAh9ZaqWnJG0AMGCJN4ik71rvpsVK4E DC1jmBPlpSg7gfFRCbG5a6zdyZO0OuGX+TKoPOfte4YVvMx1ux+W1ZB62+JXsMchlQR0u8vgzvPpv flXTcQCq12oWKA3e/GB0gQUG5YkTqBIg4oN/9Uwrd2BUsDzeLyqrHALvDEWhR5h/A/nkDJuYWcFN/ 5wvJUVyoQIx1SyVAXAOpmQ==; Date: Sat, 16 Dec 2023 14:58:27 +0200 Message-Id: <83h6kimhho.fsf@gnu.org> From: Eli Zaretskii To: Jeremy Bryant In-Reply-To: <8734w783oj.fsf@jeremybryant.net> (message from Jeremy Bryant on Tue, 12 Dec 2023 22:15:59 +0000) Subject: Re: Fwd: bug#67499: [PATCH] Add use cases of (fn) documentation facility. References: <87il5mai0x.fsf@jeremybryant.net> <834jh47h99.fsf@gnu.org> <87edg89lsn.fsf@jeremybryant.net> <83bkb890sc.fsf@gnu.org> <871qc39d9k.fsf@jeremybryant.net> <8734w783oj.fsf@jeremybryant.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 67499-done Cc: 67499-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Jeremy Bryant > Date: Tue, 12 Dec 2023 22:15:59 +0000 > > Kindly let me know if the attached patch is good to install or if > anything else is needed to work on for this bug report? Thanks, now installed on the emacs-29 branch, and closing the bug. From unknown Fri Jun 20 07:24:24 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sun, 14 Jan 2024 12:24:05 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator