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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 67499 in the body.
You can then email your comments to 67499 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Add use cases of (fn) documentation facility.
Date: Mon, 27 Nov 2023 23:30:33 +0000

[Message part 1 (text/plain, inline)]

Tags: patch


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.





> Interesting, thank you 
> Perhaps it would be of interest to add some text to the elisp manual in
> (elisp) Function Documentation

> Are there any conventions for manual additions?
> in particular to keep the number of printed pages limited is there a way
> to say 'don't print this node'?

> thanks
> Jeremy


> Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> >> One question, the elisp manual mentions that the \(fn ARGLIST) facility
> >> is particularly useful for macros.
> >>
> >> Why would we use this for defuns?
> >
> > We use it for some defuns where ELisp's arglist functionality is not
> > refined enough to express the intention of the programmer.
> > For example, the "real" arglist may be
> >
> >     name args &optional docstring &rest body
> >
> > but the intended arglist is
> >
> >     name args [docstring] &rest body
> >
> > i.e. if `docstring` is not a string it's taken as the first instruction
> > of `body`.
> >
> >
> >         Stefan

[0001-Add-use-cases-of-fn-documentation-facility.patch (text/patch, attachment)]

Message #8 received at 67499 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 67499 <at> debbugs.gnu.org
Subject: Re: 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.

Message #11 received at 67499 <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 67499 <at> debbugs.gnu.org
Subject: Re: bug#67499: [PATCH] Add use cases of (fn) documentation facility.
Date: Wed, 29 Nov 2023 23:29:58 +0000

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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 <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.

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 (text/x-diff, attachment)]

[Message part 3 (text/plain, inline)]

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

Message #14 received at 67499 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 67499 <at> debbugs.gnu.org
Subject: Re: bug#67499: [PATCH] Add use cases of (fn) documentation facility.
Date: Sat, 02 Dec 2023 15:44:35 +0200

> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Cc: 67499 <at> debbugs.gnu.org
> Date: Wed, 29 Nov 2023 23:29:58 +0000
> 
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > 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.

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 <at> 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?

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

We don't include pointers to our sources in the manual, except in very
rare cases.  I'm not sure we need to do it here.  One disadvantage of
having pointers to files is that we need to keep the pointers
up-to-date as development continues.

Thanks.

Message #17 received at 67499 <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 67499 <at> debbugs.gnu.org
Subject: Re: bug#67499: [PATCH] Add use cases of (fn) documentation facility.
Date: Sun, 03 Dec 2023 21:35:38 +0000

[0001-Add-use-cases-of-fn-documentation-facility.patch (text/x-diff, attachment)]

[Message part 2 (text/plain, inline)]

>
> 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 <at> 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 <at> gnu.org>

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

Message #20 received at 67499 <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: 67499 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Fwd: bug#67499: [PATCH] Add use cases of (fn) documentation facility.
Date: Tue, 12 Dec 2023 22:15:59 +0000

[Message part 1 (text/plain, inline)]

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

[0001-Add-use-cases-of-fn-documentation-facility.patch (text/x-diff, attachment)]

Message #23 received at 67499 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 67499 <at> debbugs.gnu.org
Subject: Re: Fwd: bug#67499: [PATCH] Add use cases of (fn) documentation
 facility.
Date: Fri, 15 Dec 2023 15:50:57 +0200

> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Date: Tue, 12 Dec 2023 22:15:59 +0000
> 
> 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.

Usually two weeks with no progress are a good reason for a ping.

I will get to this soon.

Message #28 received at 67499-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 67499-done <at> debbugs.gnu.org
Subject: Re: Fwd: bug#67499: [PATCH] Add use cases of (fn) documentation
 facility.
Date: Sat, 16 Dec 2023 14:58:27 +0200

> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Date: Tue, 12 Dec 2023 22:15:59 +0000
> 
> 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?

Thanks, now installed on the emacs-29 branch, and closing the bug.

Previous Next

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