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

From: Jeremy Bryant <[email-masked]>
Date: Sun, 03 Dec 2023 21:35:38 +0000

>From 3f427ea7e437a83b5e62121032d0352abf6b4bd8 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <[email-masked]>
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 <[email-masked]>
---
 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

>
> 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 <[email-masked]>

If this is all suitable to install I agree to close the original bug.