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

[Jeremy Bryant]

Eli Zaretskii <eliz@gnu.org> writes:

>> 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" <bug-gnu-emacs@gnu.org>
>> 
>> 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.

Understood, and substantially rewritten as attached, as an @itemize'd list.

The reader can then use find-function at point in the info manual, to
 read the code.

0001-Add-use-cases-of-fn-documentation-facility.patch
Description: Text Data

>
> 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.

Added @file and @code for all applicable markups.


In summary, the new compact text should help new contributors understand how the
(fn) magic can be used.

If it's not good to install, please let me know what to do.