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#67499: [PATCH] Add use cases of (fn) documentation facility. Date: Sat, 02 Dec 2023 15:44:35 +0200 Message-ID: <83bkb890sc.fsf@gnu.org> References: <87il5mai0x.fsf@jeremybryant.net> <834jh47h99.fsf@gnu.org> <87edg89lsn.fsf@jeremybryant.net> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="33279"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 67499@debbugs.gnu.org To: Jeremy Bryant Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Dec 02 14:45:13 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 1r9QIy-0008Ly-Ja for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 02 Dec 2023 14:45:12 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r9QIk-0000Bp-3q; Sat, 02 Dec 2023 08:44:58 -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 1r9QIf-0008TU-3Z for bug-gnu-emacs@gnu.org; Sat, 02 Dec 2023 08:44:56 -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 1r9QIe-0001Iw-Rv for bug-gnu-emacs@gnu.org; Sat, 02 Dec 2023 08:44:52 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1r9QIn-0007cb-QZ for bug-gnu-emacs@gnu.org; Sat, 02 Dec 2023 08:45:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 02 Dec 2023 13:45:01 +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.170152469429268 (code B ref 67499); Sat, 02 Dec 2023 13:45:01 +0000 Original-Received: (at 67499) by debbugs.gnu.org; 2 Dec 2023 13:44:54 +0000 Original-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 Original-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 Original-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==; In-Reply-To: <87edg89lsn.fsf@jeremybryant.net> (message from Jeremy Bryant on Wed, 29 Nov 2023 23:29:58 +0000) 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:275379 Archived-At: > 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.