GNU bug report logs - #67499
[PATCH] Add use cases of (fn) documentation facility.

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 67499 <at> debbugs.gnu.org
Subject: bug#67499: [PATCH] Add use cases of (fn) documentation facility.
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" <bug-gnu-emacs <at> 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.

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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.