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: 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> References: <87il5mai0x.fsf@jeremybryant.net> <834jh47h99.fsf@gnu.org> <87edg89lsn.fsf@jeremybryant.net> <83bkb890sc.fsf@gnu.org> <871qc39d9k.fsf@jeremybryant.net> 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="25785"; mail-complaints-to="usenet@ciao.gmane.io" To: 67499@debbugs.gnu.org, Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Dec 12 23:20:17 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 1rDB6s-0006Re-Qh for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 12 Dec 2023 23:20:17 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rDB6S-0001TM-Fl; Tue, 12 Dec 2023 17:19:48 -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 1rDB6Q-0001T8-Vp for bug-gnu-emacs@gnu.org; Tue, 12 Dec 2023 17:19:47 -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 1rDB6Q-0005l6-NT for bug-gnu-emacs@gnu.org; Tue, 12 Dec 2023 17:19:46 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rDB6f-0002km-TV for bug-gnu-emacs@gnu.org; Tue, 12 Dec 2023 17:20:01 -0500 X-Loop: help-debbugs@gnu.org In-Reply-To: <87il5mai0x.fsf@jeremybryant.net> Resent-From: Jeremy Bryant Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 12 Dec 2023 22:20: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.170241956910533 (code B ref 67499); Tue, 12 Dec 2023 22:20:01 +0000 Original-Received: (at 67499) by debbugs.gnu.org; 12 Dec 2023 22:19:29 +0000 Original-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 Original-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 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. 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:276096 Archived-At: --=-=-= 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 --=-=-=--