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

From: Eli Zaretskii <[email-masked]>
Date: Wed, 29 Nov 2023 16:42:42 +0200

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