bug#67499: Fwd: bug#67499: [PATCH] Add use cases of (fn) documentation facility.

[Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 1990 bytes --]


Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org> 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 <eliz@gnu.org>
>
> 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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-use-cases-of-fn-documentation-facility.patch --]
[-- Type: text/x-diff, Size: 1689 bytes --]

From 3f427ea7e437a83b5e62121032d0352abf6b4bd8 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
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 <eliz@gnu.org>
---
 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