unofficial mirror of help-gnu-emacs@gnu.org
 help / color / mirror / Atom feed
* Lisp error on function :documentation
@ 2022-10-15 23:48 Heime via Users list for the GNU Emacs text editor
  2022-10-16  2:48 ` Michael Heerdegen
  2022-10-16  3:56 ` Stefan Monnier via Users list for the GNU Emacs text editor
  0 siblings, 2 replies; 39+ messages in thread
From: Heime via Users list for the GNU Emacs text editor @ 2022-10-15 23:48 UTC (permalink / raw)
  To: help-gnu-emacs@gnu.org

I am getting the following lisp error: (void-function :documentation). Seems correct to me.

(defun ivy-config ()

(:documentation (concat "Ivy completion.\n\n" ivy-details))

(add-to-list 'load-path "~/contrib/ivy"))

(require 'ivy)
(require 'counsel)
(require 'swiper)

;; Enable this if you want `swiper' to use it
;; (setq search-default-mode #'char-fold-to-regexp)

(setq ivy-use-virtual-buffers t)
(setq enable-recursive-minibuffers t)
(tachyon-ivy-ktrigr) )

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-15 23:48 Lisp error on function :documentation Heime via Users list for the GNU Emacs text editor
@ 2022-10-16  2:48 ` Michael Heerdegen
  2022-10-16  2:59   ` Heime
  2022-10-16  3:56 ` Stefan Monnier via Users list for the GNU Emacs text editor
  1 sibling, 1 reply; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-16  2:48 UTC (permalink / raw)
  To: help-gnu-emacs

Heime via Users list for the GNU Emacs text editor
<help-gnu-emacs@gnu.org> writes:

> I am getting the following lisp error: (void-function
> :documentation). Seems correct to me.
>
> (defun ivy-config ()
>
> (:documentation (concat "Ivy completion.\n\n" ivy-details))

I think it's better to avoid undocumented features unless absolutely
sure how they work or being able to find out.

Michael.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16  2:48 ` Michael Heerdegen
@ 2022-10-16  2:59   ` Heime
  2022-10-16  3:37     ` Michael Heerdegen
  0 siblings, 1 reply; 39+ messages in thread
From: Heime @ 2022-10-16  2:59 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: help-gnu-emacs

------- Original Message -------
On Sunday, October 16th, 2022 at 2:48 AM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> Heime via Users list for the GNU Emacs text editor
> help-gnu-emacs@gnu.org writes:
> 
> > I am getting the following lisp error: (void-function
> > :documentation). Seems correct to me.
> > 
> > (defun ivy-config ()
> > 
> > (:documentation (concat "Ivy completion.\n\n" ivy-details))
> 
> 
> I think it's better to avoid undocumented features unless absolutely
> sure how they work or being able to find out.
> 
> Michael.

The intention was to be able to append more detailed documentation
to the docstring, without having the documentation part of the function
too long.  Is there something equivalent to the undocumented use of 
":documentation" ?  

Otherwise, I would have to append it after defining the function, which is
not ideal.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16  2:59   ` Heime
@ 2022-10-16  3:37     ` Michael Heerdegen
  2022-10-16  3:50       ` Heime
  0 siblings, 1 reply; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-16  3:37 UTC (permalink / raw)
  To: help-gnu-emacs

Heime <heimeborgia@protonmail.com> writes:

> Is there something equivalent to the undocumented use of
> ":documentation" ?

Use the function-documentation property of the function's name.  Lots of
examples in the sources.

Michael.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16  3:37     ` Michael Heerdegen
@ 2022-10-16  3:50       ` Heime
  2022-10-16  4:12         ` Michael Heerdegen
  0 siblings, 1 reply; 39+ messages in thread
From: Heime @ 2022-10-16  3:50 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: help-gnu-emacs

------- Original Message -------
On Sunday, October 16th, 2022 at 3:37 AM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> Heime heimeborgia@protonmail.com writes:
> 
> > Is there something equivalent to the undocumented use of
> > ":documentation" ?
> 
> 
> Use the function-documentation property of the function's name. Lots of
> examples in the sources.
> 
> Michael.

Yielded the following.  That's it right ?  But I see that the original docstring
gets deleted.  Any way to avoid this and be able to append to the initial docstring? 

(defvar icstyle-details "Some more details")

(defun icstyle (sty)
   
   "Set style used for alerting user about possible minibuffer completions."
   
   (put 'icstyle 'function-documentation icstyle-details)





^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-15 23:48 Lisp error on function :documentation Heime via Users list for the GNU Emacs text editor
  2022-10-16  2:48 ` Michael Heerdegen
@ 2022-10-16  3:56 ` Stefan Monnier via Users list for the GNU Emacs text editor
  2022-10-16  4:00   ` Heime
  1 sibling, 1 reply; 39+ messages in thread
From: Stefan Monnier via Users list for the GNU Emacs text editor @ 2022-10-16  3:56 UTC (permalink / raw)
  To: help-gnu-emacs

Heime via Users list for the GNU Emacs text editor [2022-10-15 23:48:31] wrote:
> I am getting the following lisp error: (void-function :documentation). Seems correct to me.
>
> (defun ivy-config ()
>   (:documentation (concat "Ivy completion.\n\n" ivy-details))
>   (add-to-list 'load-path "~/contrib/ivy"))

Works for me.  Is your Emacs simply too old?


        Stefan




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16  3:56 ` Stefan Monnier via Users list for the GNU Emacs text editor
@ 2022-10-16  4:00   ` Heime
  2022-10-16  4:05     ` Michael Heerdegen
  2022-10-16  4:07     ` Stefan Monnier
  0 siblings, 2 replies; 39+ messages in thread
From: Heime @ 2022-10-16  4:00 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: help-gnu-emacs





------- Original Message -------
On Sunday, October 16th, 2022 at 3:56 AM, Stefan Monnier via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> wrote:


> Heime via Users list for the GNU Emacs text editor [2022-10-15 23:48:31] wrote:
> 
> > I am getting the following lisp error: (void-function :documentation). Seems correct to me.
> > 
> > (defun ivy-config ()
> > (:documentation (concat "Ivy completion.\n\n" ivy-details))
> > (add-to-list 'load-path "~/contrib/ivy"))
> 
> 
> Works for me. Is your Emacs simply too old?

Would not think so.  Emacs 29.0.50 actually.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16  4:00   ` Heime
@ 2022-10-16  4:05     ` Michael Heerdegen
  2022-10-16  4:07     ` Stefan Monnier
  1 sibling, 0 replies; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-16  4:05 UTC (permalink / raw)
  To: help-gnu-emacs

Heime <heimeborgia@protonmail.com> writes:

> Would not think so.  Emacs 29.0.50 actually.

lexical-binding off maybe?

Michael.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16  4:00   ` Heime
  2022-10-16  4:05     ` Michael Heerdegen
@ 2022-10-16  4:07     ` Stefan Monnier
  1 sibling, 0 replies; 39+ messages in thread
From: Stefan Monnier @ 2022-10-16  4:07 UTC (permalink / raw)
  To: Heime; +Cc: help-gnu-emacs

>> > (defun ivy-config ()
>> > (:documentation (concat "Ivy completion.\n\n" ivy-details))
>> > (add-to-list 'load-path "~/contrib/ivy"))
>> 
>> 
>> Works for me. Is your Emacs simply too old?
>
> Would not think so.  Emacs 29.0.50 actually.

Than you might want to give more details about what you've done since
what I understood of what you've done does not result in the error
you showed.

    /usr/bin/emacs -Q
    M-x ielm RET
    (defun ivy-config ()
       (:documentation (concat "Ivy completion.\n\n" ivy-details))
       (add-to-list 'load-path "~/contrib/ivy"))
    RET

complains that "Symbol’s value as variable is void: ivy-details", which
indicates that it understood `:documentation` correctly (i.e. it
processed it when creating the function rather than later when we call
it).


        Stefan




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16  3:50       ` Heime
@ 2022-10-16  4:12         ` Michael Heerdegen
  2022-10-16  4:30           ` Heime
  2022-10-16 15:23           ` Stefan Monnier via Users list for the GNU Emacs text editor
  0 siblings, 2 replies; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-16  4:12 UTC (permalink / raw)
  To: Heime; +Cc: help-gnu-emacs

Heime <heimeborgia@protonmail.com> writes:

> Yielded the following.  That's it right ?

Depends on where you put the missing closing paren.  In the correct
version the `put' statement is not part of the defun.

> But I see that the original docstring gets deleted.  Any way to avoid
> this and be able to append to the initial docstring?

Yes - see `pcase' for example, but that requires a bit of work - and
that stuff is also not documented.  One can learn it by reading the
examples in the sources.  Not totally trivial, unfortunately.

Or maybe someone has added some nicer solution in the meantime? - I
don't recall.

Michael.



^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16  4:12         ` Michael Heerdegen
@ 2022-10-16  4:30           ` Heime
  2022-10-16 22:53             ` Michael Heerdegen
  2022-10-16 15:23           ` Stefan Monnier via Users list for the GNU Emacs text editor
  1 sibling, 1 reply; 39+ messages in thread
From: Heime @ 2022-10-16  4:30 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: help-gnu-emacs

------- Original Message -------
On Sunday, October 16th, 2022 at 4:12 AM, Michael Heerdegen <michael_heerdegen@web.de> wrote:

> Heime heimeborgia@protonmail.com writes:
> 
> > Yielded the following. That's it right ?
> 
> 
> Depends on where you put the missing closing paren. In the correct
> version the `put' statement is not part of the defun.

I actually introduced the "put" command inside the function after the
initial docstring.  And it did work. 
 
> > But I see that the original docstring gets deleted. Any way to avoid
> > this and be able to append to the initial docstring?
> 
> 
> Yes - see `pcase' for example, but that requires a bit of work - and
> that stuff is also not documented. One can learn it by reading the
> examples in the sources. Not totally trivial, unfortunately.
> 
> Or maybe someone has added some nicer solution in the meantime? - I
> don't recall.
> 
> Michael.

It would be useful to append another string variable to the initial 
docstring inside the function.  Avoids functions with long docstring
parts.

You were correct about the lexical binding part.

I had 

;; file.el
;; -*- lexical-binding: t; -*-

Does not seem the right way to call "lexical-binding".

Putting on the first line got the documentation correct.

;; -*- lexical-binding: t; -*-

But, perhaps it is not so good to include this undocumented feature.



^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16  4:12         ` Michael Heerdegen
  2022-10-16  4:30           ` Heime
@ 2022-10-16 15:23           ` Stefan Monnier via Users list for the GNU Emacs text editor
  2022-10-16 22:58             ` Michael Heerdegen
  1 sibling, 1 reply; 39+ messages in thread
From: Stefan Monnier via Users list for the GNU Emacs text editor @ 2022-10-16 15:23 UTC (permalink / raw)
  To: help-gnu-emacs

> Or maybe someone has added some nicer solution in the meantime? - I
> don't recall.

I don't know about nicer, but in Emacs-29, you can use `oclosure-lambda`
to build a function tagged with a certain type on which you can dispatch
via `cl-defmethod` and functions's docstrings are fetched via
`function-documentation` which is a generic function to which you can
add your own methods for your OClosure type, thus making it possible to
dynamically build your docstring.

We use it internally for the "accessor" functions that let you fetch the
value of an OClosure's slot:

    (oclosure-define accessor
      "OClosure function to access a specific slot of an object."
      type slot)

    (cl-defmethod function-documentation ((function accessor))
      (oclosure--accessor-docstring function)) ;; FIXME: η-reduce!

    (defun oclosure--accessor-docstring (f)
      ;; This would like to be a (cl-defmethod function-documentation ...)
      ;; but for circularity reason the defmethod is in `simple.el'.
      (format "Access slot \"%S\" of OBJ of type `%S'.\n\n(fn OBJ)"
              (accessor--slot f) (accessor--type f)))

We could of course also prebuild those docstrings when we define each
accessor function, but with the above we avoid this cost upfront and
instead we compute those docstrings ondemand.

See also the `OClosures` section in the Texinfo docs.


        Stefan




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16  4:30           ` Heime
@ 2022-10-16 22:53             ` Michael Heerdegen
  2022-10-16 23:08               ` Heime
  0 siblings, 1 reply; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-16 22:53 UTC (permalink / raw)
  To: help-gnu-emacs

Heime <heimeborgia@protonmail.com> writes:

> I actually introduced the "put" command inside the function after the
> initial docstring.  And it did work. 

Please answer yourself why and if this is a good idea to do.

Michael.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16 15:23           ` Stefan Monnier via Users list for the GNU Emacs text editor
@ 2022-10-16 22:58             ` Michael Heerdegen
  2022-10-16 23:09               ` Heime
  0 siblings, 1 reply; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-16 22:58 UTC (permalink / raw)
  To: help-gnu-emacs

Stefan Monnier via Users list for the GNU Emacs text editor
<help-gnu-emacs@gnu.org> writes:

> > Or maybe someone has added some nicer solution in the meantime? - I
> > don't recall.
>
> I don't know about nicer, but in Emacs-29, you can use `oclosure-lambda`
> to build a function tagged with a certain type on which you can dispatch
> via `cl-defmethod` and functions's docstrings are fetched via
> `function-documentation` which is a generic function to which you can
> add your own methods for your OClosure type, thus making it possible to
> dynamically build your docstring.

Oh, I think this was what I remembered, thanks.  It's IMO much nicer than
this messing with innards we used to do.  It's also easier to learn.

Or has using an oclosure just for the purpose of dynamical docstring
generation (larger) downsides?

Michael.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16 22:53             ` Michael Heerdegen
@ 2022-10-16 23:08               ` Heime
  2022-10-16 23:23                 ` Michael Heerdegen
  0 siblings, 1 reply; 39+ messages in thread
From: Heime @ 2022-10-16 23:08 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: help-gnu-emacs

------- Original Message -------
On Sunday, October 16th, 2022 at 10:53 PM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> Heime heimeborgia@protonmail.com writes:
> 
> > I actually introduced the "put" command inside the function after the
> > initial docstring. And it did work.
> 
> 
> Please answer yourself why and if this is a good idea to do.
> 
> Michael.

I have no interest in people with the "answer yourself" rant.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16 22:58             ` Michael Heerdegen
@ 2022-10-16 23:09               ` Heime
  2022-10-16 23:25                 ` Michael Heerdegen
  2022-10-17  1:00                 ` Stefan Monnier via Users list for the GNU Emacs text editor
  0 siblings, 2 replies; 39+ messages in thread
From: Heime @ 2022-10-16 23:09 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: help-gnu-emacs

------- Original Message -------
On Sunday, October 16th, 2022 at 10:58 PM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> Stefan Monnier via Users list for the GNU Emacs text editor
> help-gnu-emacs@gnu.org writes:
> 
> > > Or maybe someone has added some nicer solution in the meantime? - I
> > > don't recall.
> > 
> > I don't know about nicer, but in Emacs-29, you can use `oclosure-lambda`
> > to build a function tagged with a certain type on which you can dispatch
> > via `cl-defmethod` and functions's docstrings are fetched via
> > `function-documentation` which is a generic function to which you can
> > add your own methods for your OClosure type, thus making it possible to
> > dynamically build your docstring.
> 
> 
> Oh, I think this was what I remembered, thanks. It's IMO much nicer than
> this messing with innards we used to do. It's also easier to learn.
> 
> Or has using an oclosure just for the purpose of dynamical docstring
> generation (larger) downsides?
> 
> Michael.

You all seem more interested in trying to satisfy your intellect than helping
out on the actual question by the OP.



^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16 23:08               ` Heime
@ 2022-10-16 23:23                 ` Michael Heerdegen
  0 siblings, 0 replies; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-16 23:23 UTC (permalink / raw)
  To: Heime; +Cc: help-gnu-emacs

Heime <heimeborgia@protonmail.com> writes:

> I have no interest in people with the "answer yourself" rant.

Wasn't a rant.  Was my suggestion.  I think a good one.  I'm
allowed to have my own opinion how a good answer looks like.  You don't
have to agree.

Michael.



^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16 23:09               ` Heime
@ 2022-10-16 23:25                 ` Michael Heerdegen
  2022-10-16 23:39                   ` Heime
  2022-10-17  1:00                 ` Stefan Monnier via Users list for the GNU Emacs text editor
  1 sibling, 1 reply; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-16 23:25 UTC (permalink / raw)
  To: Heime; +Cc: help-gnu-emacs

Heime <heimeborgia@protonmail.com> writes:

> You all seem more interested in trying to satisfy your intellect than
> helping out on the actual question by the OP.

Sorry, but there just _is_ no simpler solution.  What do you think I
should do???

Michael.



^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16 23:25                 ` Michael Heerdegen
@ 2022-10-16 23:39                   ` Heime
  2022-10-16 23:43                     ` Michael Heerdegen
  0 siblings, 1 reply; 39+ messages in thread
From: Heime @ 2022-10-16 23:39 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: help-gnu-emacs

------- Original Message -------
On Sunday, October 16th, 2022 at 11:25 PM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> Heime heimeborgia@protonmail.com writes:
>
> > You all seem more interested in trying to satisfy your intellect than
> > helping out on the actual question by the OP.
>
>
> Sorry, but there just is no simpler solution. What do you think I
> should do???
>
> Michael.

What am I to do with "use `oclosure-lambda` to build a function tagged with a 
certain type on which you can dispatch via `cl-defmethod`".

If you know, say you know, and give short example.  As I have shown example 
on what I had used.  And if you don't know, say you don't know.  Simple.

Anyway.  There is no easy and straightforward way to add a predefined string
to a brief documentation string which is documented.  It seems.

The lexical binding solved the problem.  If something works my conclusion is that
I keep it.  If people know better they should tell me.  Also very simple.





^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16 23:39                   ` Heime
@ 2022-10-16 23:43                     ` Michael Heerdegen
  2022-10-17  0:07                       ` Heime
  0 siblings, 1 reply; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-16 23:43 UTC (permalink / raw)
  To: Heime; +Cc: help-gnu-emacs

Heime <heimeborgia@protonmail.com> writes:

> Anyway.  There is no easy and straightforward way to add a predefined
> string to a brief documentation string which is documented.  It seems.

Exactly that.  And what would it help if we send you some code you would
not understand?  You don't want or don't have time learn that all, and I
don't have time to work that all out.

Michael.



^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16 23:43                     ` Michael Heerdegen
@ 2022-10-17  0:07                       ` Heime
  2022-10-17  0:15                         ` Michael Heerdegen
  0 siblings, 1 reply; 39+ messages in thread
From: Heime @ 2022-10-17  0:07 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: help-gnu-emacs

------- Original Message -------
On Sunday, October 16th, 2022 at 11:43 PM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> Heime heimeborgia@protonmail.com writes:
> 
> > Anyway. There is no easy and straightforward way to add a predefined
> > string to a brief documentation string which is documented. It seems.
> 
> 
> Exactly that. And what would it help if we send you some code you would
> not understand? You don't want or don't have time learn that all, and I
> don't have time to work that all out.
> 
> Michael.

Then let us hope some genius crops up and writes a solution that solves
the impasse.  




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  0:07                       ` Heime
@ 2022-10-17  0:15                         ` Michael Heerdegen
  2022-10-17  1:01                           ` Heime
  2022-10-17  1:01                           ` Stefan Monnier via Users list for the GNU Emacs text editor
  0 siblings, 2 replies; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-17  0:15 UTC (permalink / raw)
  To: help-gnu-emacs

Heime <heimeborgia@protonmail.com> writes:

> Then let us hope some genius crops up and writes a solution that solves
> the impasse.  

BTW, what Stefan had sent was more or less the most perfect example one
can give.  You can use it as a template.  You would have to get familiar
with generic functions, however.

Michael.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-16 23:09               ` Heime
  2022-10-16 23:25                 ` Michael Heerdegen
@ 2022-10-17  1:00                 ` Stefan Monnier via Users list for the GNU Emacs text editor
  2022-10-17  1:55                   ` Heime
  1 sibling, 1 reply; 39+ messages in thread
From: Stefan Monnier via Users list for the GNU Emacs text editor @ 2022-10-17  1:00 UTC (permalink / raw)
  To: help-gnu-emacs

Heime [2022-10-16 23:09:08] wrote:
> You all seem more interested in trying to satisfy your intellect than
> helping out on the actual question by the OP.

I'm definitely here to satisfy my intellect: guilty as charged.

But as for the OP, I showed how I tried to reproduce it, and how
`:documentation` worked for me.  I'm not sure what more I can do at that
point: I'm just waiting for a description of the OP that's precise
enough to be reproduced.

And in the mean time, I'm promoting OClosures :-)


        Stefan




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  0:15                         ` Michael Heerdegen
@ 2022-10-17  1:01                           ` Heime
  2022-10-17  1:15                             ` Michael Heerdegen
  2022-10-17  1:01                           ` Stefan Monnier via Users list for the GNU Emacs text editor
  1 sibling, 1 reply; 39+ messages in thread
From: Heime @ 2022-10-17  1:01 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: help-gnu-emacs

------- Original Message -------
On Monday, October 17th, 2022 at 12:15 AM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> Heime heimeborgia@protonmail.com writes:
> 
> > Then let us hope some genius crops up and writes a solution that solves
> > the impasse.
> 
> 
> BTW, what Stefan had sent was more or less the most perfect example one
> can give. You can use it as a template. You would have to get familiar
> with generic functions, however.
> 
> Michael.

Yes.  Still, someone commented that being undocumented, it is not really
suitable for use.  

Then I started doing

(defvar details "Some details here")

(defun navscan ()

   (put 'navscan 'function-documentation

      (concat "Set style about possible.\n\n" details))

Which seems not good either, as I picked up from the discussion.

Thusly the only real solution is to call the "(put" part after
defining the function.

Would appreciate if people answer clearly.

Being able to append a details string to the function documentation
at the position where the documentation is supposed to be located (after
the function name declaration), would be valuable in following the code better.  
 




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  0:15                         ` Michael Heerdegen
  2022-10-17  1:01                           ` Heime
@ 2022-10-17  1:01                           ` Stefan Monnier via Users list for the GNU Emacs text editor
  2022-10-17  1:22                             ` Michael Heerdegen
  1 sibling, 1 reply; 39+ messages in thread
From: Stefan Monnier via Users list for the GNU Emacs text editor @ 2022-10-17  1:01 UTC (permalink / raw)
  To: help-gnu-emacs

Michael Heerdegen [2022-10-17 02:15:37] wrote:
> Heime <heimeborgia@protonmail.com> writes:
>> Then let us hope some genius crops up and writes a solution that solves
>> the impasse.  
>
> BTW, what Stefan had sent was more or less the most perfect example one
> can give.  You can use it as a template.  You would have to get familiar
> with generic functions, however.

If `:documentation` does what he needs, it's a *much* simpler solution.


        Stefan "to be blamed for both `:documentation` and OClosures"




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  1:01                           ` Heime
@ 2022-10-17  1:15                             ` Michael Heerdegen
  0 siblings, 0 replies; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-17  1:15 UTC (permalink / raw)
  To: Heime; +Cc: help-gnu-emacs

Heime <heimeborgia@protonmail.com> writes:

> Thusly the only real solution is to call the "(put" part after
> defining the function.

The :documentation thing is a kind of declaration.  That `put' is just
Elisp (code) - an expression.  If it's part of other code it's only
evaluated whenever you evaluate that code (call the function, in this
case).

Michael.



^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  1:01                           ` Stefan Monnier via Users list for the GNU Emacs text editor
@ 2022-10-17  1:22                             ` Michael Heerdegen
  2022-10-17  1:27                               ` Michael Heerdegen
  2022-10-17  2:08                               ` Heime
  0 siblings, 2 replies; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-17  1:22 UTC (permalink / raw)
  To: help-gnu-emacs

Stefan Monnier via Users list for the GNU Emacs text editor
<help-gnu-emacs@gnu.org> writes:

> If `:documentation` does what he needs, it's a *much* simpler solution.
>
>         Stefan "to be blamed for both `:documentation` and OClosures"

To be blamed to show up too late here, first and foremost.

Ok, so the argument of :documentation is a form that is eval'led
dynamically, and not only when the definition is evaluated, is that
correct?  Then it would be the simplest solution by far indeed.

Michael.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  1:22                             ` Michael Heerdegen
@ 2022-10-17  1:27                               ` Michael Heerdegen
  2022-10-17  2:08                               ` Heime
  1 sibling, 0 replies; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-17  1:27 UTC (permalink / raw)
  To: help-gnu-emacs

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Ok, so the argument of :documentation is a form that is eval'led
> dynamically, and not only when the definition is evaluated, is that
> correct?  Then it would be the simplest solution by far indeed.

Is it maybe time to :document, eh, I mean, to document this feature
now?

Michael.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  1:00                 ` Stefan Monnier via Users list for the GNU Emacs text editor
@ 2022-10-17  1:55                   ` Heime
  2022-10-17 12:28                     ` Stefan Monnier
  0 siblings, 1 reply; 39+ messages in thread
From: Heime @ 2022-10-17  1:55 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: help-gnu-emacs


------- Original Message -------
On Monday, October 17th, 2022 at 1:00 AM, Stefan Monnier via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> wrote:


> Heime [2022-10-16 23:09:08] wrote:
> 
> > You all seem more interested in trying to satisfy your intellect than
> > helping out on the actual question by the OP.
> 
> 
> I'm definitely here to satisfy my intellect: guilty as charged.
> 
> But as for the OP, I showed how I tried to reproduce it, and how
> `:documentation` worked for me. I'm not sure what more I can do at that
> point: I'm just waiting for a description of the OP that's precise
> enough to be reproduced.

Was able to get it work with the lexical binding setup, which was not working
as expected.  I had no criticisms about your response.  My only difficulty
is whether you recommend using such undocumented feature (commonly people vote
against using them).  Being able to append to the documentation part a details
string is very strong programmatically.  I would like that an equivalent 
implementation be done and documented for public use.  Otherwise I would continue
having to delay the addition until after the function definition.   

> And in the mean time, I'm promoting OClosures :-)
> 
> Stefan

As for closures, the recommendation against examining and altering the
structure of closure objects indicates that something very wrong in going
on. 




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  1:22                             ` Michael Heerdegen
  2022-10-17  1:27                               ` Michael Heerdegen
@ 2022-10-17  2:08                               ` Heime
  2022-10-17  2:42                                 ` Michael Heerdegen
  1 sibling, 1 reply; 39+ messages in thread
From: Heime @ 2022-10-17  2:08 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: help-gnu-emacs


------- Original Message -------
On Monday, October 17th, 2022 at 1:22 AM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> Stefan Monnier via Users list for the GNU Emacs text editor
> help-gnu-emacs@gnu.org writes:
> 
> > If `:documentation` does what he needs, it's a much simpler solution.
> > 
> > Stefan "to be blamed for both `:documentation` and OClosures"
> 
> 
> To be blamed to show up too late here, first and foremost.
> 
> Ok, so the argument of :documentation is a form that is eval'led
> dynamically, and not only when the definition is evaluated, is that
> correct? Then it would be the simplest solution by far indeed.
> 
> Michael.

That was my implementation.  After all, I did do my homework.  If the
emacs maintainers can clear up recommendations against using undocumented
features (allowing use of :documentation it a defun as acceptable, or providing
alternative that is acceptable and does the equivalent), life would be good.



^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  2:08                               ` Heime
@ 2022-10-17  2:42                                 ` Michael Heerdegen
  2022-10-17  3:03                                   ` Heime
  0 siblings, 1 reply; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-17  2:42 UTC (permalink / raw)
  To: Heime; +Cc: help-gnu-emacs

Heime <heimeborgia@protonmail.com> writes:

> That was my implementation.  After all, I did do my homework.

Indeed.

> If the emacs maintainers can clear up recommendations against using
> undocumented features (allowing use of :documentation it a defun as
> acceptable, or providing alternative that is acceptable and does the
> equivalent), life would be good.

This :documentation thing is a quite new feature.  It just has no
documentation yet.  Hope it will get some soon.  Then life would be even
better.

Michael.



^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  2:42                                 ` Michael Heerdegen
@ 2022-10-17  3:03                                   ` Heime
  2022-10-17  3:19                                     ` Emanuel Berg
  0 siblings, 1 reply; 39+ messages in thread
From: Heime @ 2022-10-17  3:03 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: help-gnu-emacs


------- Original Message -------
On Monday, October 17th, 2022 at 2:42 AM, Michael Heerdegen <michael_heerdegen@web.de> wrote:


> Heime heimeborgia@protonmail.com writes:
> 
> > That was my implementation. After all, I did do my homework.
> 
> 
> Indeed.
> 
> > If the emacs maintainers can clear up recommendations against using
> > undocumented features (allowing use of :documentation it a defun as
> > acceptable, or providing alternative that is acceptable and does the
> > equivalent), life would be good.
> 
> 
> This :documentation thing is a quite new feature. It just has no
> documentation yet. Hope it will get some soon. Then life would be even
> better.
> 
> Michael.

Fine.  I had reasoned it was undocumented because maintainers did not
want package developers to use it.  In other words, that it was designed
and meant for proper use in emacs internals only.  But I used it anyway.



^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  3:03                                   ` Heime
@ 2022-10-17  3:19                                     ` Emanuel Berg
  0 siblings, 0 replies; 39+ messages in thread
From: Emanuel Berg @ 2022-10-17  3:19 UTC (permalink / raw)
  To: help-gnu-emacs

Heime wrote:

> I had reasoned it was undocumented because maintainers did
> not want package developers to use it. In other words, that
> it was designed and meant for proper use in emacs
> internals only.

It doesn't work that way ...

-- 
underground experts united
https://dataswamp.org/~incal




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17  1:55                   ` Heime
@ 2022-10-17 12:28                     ` Stefan Monnier
  2022-10-17 13:15                       ` Emanuel Berg
  2022-10-18  0:51                       ` Michael Heerdegen
  0 siblings, 2 replies; 39+ messages in thread
From: Stefan Monnier @ 2022-10-17 12:28 UTC (permalink / raw)
  To: Heime; +Cc: help-gnu-emacs

> Was able to get it work with the lexical binding setup, which was not working
> as expected.  I had no criticisms about your response.  My only difficulty
> is whether you recommend using such undocumented feature (commonly people vote
> against using them).

It's documented in `etc/NEWS.25` but indeed not in the ELisp reference manual.
That's a (documentation) bug.

>> And in the mean time, I'm promoting OClosures :-)
> As for closures, the recommendation against examining and altering the
> structure of closure objects indicates that something very wrong in
> going on.

OClosures are a generalization of closures where you specify parts which
are officially exposed.  You can think of them as callable objects.


        Stefan




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17 12:28                     ` Stefan Monnier
@ 2022-10-17 13:15                       ` Emanuel Berg
  2022-10-17 19:27                         ` tomas
  2022-10-18  0:51                       ` Michael Heerdegen
  1 sibling, 1 reply; 39+ messages in thread
From: Emanuel Berg @ 2022-10-17 13:15 UTC (permalink / raw)
  To: help-gnu-emacs

Stefan Monnier wrote:

> OClosures are a generalization of closures where you specify
> parts which are officially exposed. You can think of them as
> callable objects.

Hm, what does "generalization" mean, here?

I was always puzzled by that word ...

Because that sounds like it is _less_ general, or more
precisely it sounds like it is a particular implementation of
a broader concept with specific details of its own?

-- 
underground experts united
https://dataswamp.org/~incal




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17 13:15                       ` Emanuel Berg
@ 2022-10-17 19:27                         ` tomas
  2022-10-17 21:32                           ` Emanuel Berg
  0 siblings, 1 reply; 39+ messages in thread
From: tomas @ 2022-10-17 19:27 UTC (permalink / raw)
  To: help-gnu-emacs

[-- Attachment #1: Type: text/plain, Size: 586 bytes --]

On Mon, Oct 17, 2022 at 03:15:21PM +0200, Emanuel Berg wrote:
> Stefan Monnier wrote:
> 
> > OClosures are a generalization of closures where you specify
> > parts which are officially exposed. You can think of them as
> > callable objects.
> 
> Hm, what does "generalization" mean, here?

It means that a regular closure is a special case of an OClosure,
where all slots are hidden. Turning that around, an OClosure is
a generalization of a closure where some slots are visible.

> I was always puzzled by that word ...

Aren't words puzzling?

;-)

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17 19:27                         ` tomas
@ 2022-10-17 21:32                           ` Emanuel Berg
  0 siblings, 0 replies; 39+ messages in thread
From: Emanuel Berg @ 2022-10-17 21:32 UTC (permalink / raw)
  To: help-gnu-emacs

tomas wrote:

> It means that a regular closure is a special case of an
> OClosure, where all slots are hidden.

A regular closure is a _special_ case?

> Turning that around, an OClosure is a generalization of
> a closure where some slots are visible.

I'm only aware of the lexical/static let-closure which is
a `let' with a (one or several) `defun' within it.

I have found two use cases,

(1) share variables between functions; and

(2) have persistent (state) variable values between
    function calls.

Here [last] is an interesting example that where both use
cases are present, and we further encapsulation by puting two
inner closures into one big on the outside.

I've heard that closures can also be used in general to "use
variables like they are global variables, only they aren't
really" so it is as practical, but not as bad a practice ...

However, all such cases I've had, upon closer examination,
they are actually examples of either use case (1) or (2).

As a practical note, if you consider global variables bad,
they can be, thru shuffling around function into files that
make sense - which is a good thing anyway, so you want that as
well - global variables can be virtually eliminated by
using closures. It just makes the code cooler and
more exciting!

In terms of theory they are a proto-OO system - or, if
closures were there before the OO paradigm, an OO system is an
extended system-system that's based on closures, i.e.
the coupling of functions (methods) and variables (data).

I'm not familiar with OClosure so if you'd care to show what
they look like and what they can do - actually this also
brings the thought to the OO world were certain variables
(members) are private and some are public, or better perhaps,
the variables are private and some methods (setters) are
public, and now that I write it that's what you get by default
with a let-closure, i.e., the regular one, since the variables
are just usable from the functions which, at least in Elisp,
are all one the same, public if you will, level ...

;;; -*- lexical-binding: t -*-
;;
;; this file:
;;   https://dataswamp.org/~incal/emacs-init/w3m/w3m-survivor.el

(require 'w3m-search)
(require 'cl-lib)

(let ((opts   "torrent magnet 720p")
      (show   "Survivor")
      (prompt "episode: ") )

  (let ((next 1))
    (defun australian-survivor (ep)
      (interactive (list (read-number prompt next)))
      (w3m-search w3m-search-default-engine
        (format "\"s10e%02d\" Australian %s %s" ep show opts) )
      (setq next (1+ ep)) ))

  (declare-function australian-survivor nil)
  (defalias 'aus #'australian-survivor)

  (let ((next 1))
    (defun us-survivor (ep)
      (interactive (list (read-number prompt next)))
      (w3m-search w3m-search-default-engine
        (format "\"s43e%02d\" %s %s" ep show opts) )
      (setq next (1+ ep)) ))

  (declare-function us-survivor nil)
  (defalias 'us #'us-survivor) )

-- 
underground experts united
https://dataswamp.org/~incal




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-17 12:28                     ` Stefan Monnier
  2022-10-17 13:15                       ` Emanuel Berg
@ 2022-10-18  0:51                       ` Michael Heerdegen
  2022-10-18  1:05                         ` Emanuel Berg
  1 sibling, 1 reply; 39+ messages in thread
From: Michael Heerdegen @ 2022-10-18  0:51 UTC (permalink / raw)
  To: help-gnu-emacs

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

> It's documented in `etc/NEWS.25` but indeed not in the ELisp reference
> manual.  That's a (documentation) bug.

Found it: bug#58602.

So the docstring is static after building the closure.  AFAIU the OP
also wanted to add to the docstring after defining the function.

Michael.




^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: Lisp error on function :documentation
  2022-10-18  0:51                       ` Michael Heerdegen
@ 2022-10-18  1:05                         ` Emanuel Berg
  0 siblings, 0 replies; 39+ messages in thread
From: Emanuel Berg @ 2022-10-18  1:05 UTC (permalink / raw)
  To: help-gnu-emacs

Michael Heerdegen wrote:

>> It's documented in `etc/NEWS.25` but indeed not in the
>> ELisp reference manual. That's a (documentation) bug.
>
> Found it: bug#58602.

\o/

> So the docstring is static after building the closure.

Okay, how does that look?

Closures are soo interesting!

They are the new black after `pcase-let', DWIM, the cl-lib,
lexical/static binding and setting the background to black.

-- 
underground experts united
https://dataswamp.org/~incal




^ permalink raw reply	[flat|nested] 39+ messages in thread

end of thread, other threads:[~2022-10-18  1:05 UTC | newest]

Thread overview: 39+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-10-15 23:48 Lisp error on function :documentation Heime via Users list for the GNU Emacs text editor
2022-10-16  2:48 ` Michael Heerdegen
2022-10-16  2:59   ` Heime
2022-10-16  3:37     ` Michael Heerdegen
2022-10-16  3:50       ` Heime
2022-10-16  4:12         ` Michael Heerdegen
2022-10-16  4:30           ` Heime
2022-10-16 22:53             ` Michael Heerdegen
2022-10-16 23:08               ` Heime
2022-10-16 23:23                 ` Michael Heerdegen
2022-10-16 15:23           ` Stefan Monnier via Users list for the GNU Emacs text editor
2022-10-16 22:58             ` Michael Heerdegen
2022-10-16 23:09               ` Heime
2022-10-16 23:25                 ` Michael Heerdegen
2022-10-16 23:39                   ` Heime
2022-10-16 23:43                     ` Michael Heerdegen
2022-10-17  0:07                       ` Heime
2022-10-17  0:15                         ` Michael Heerdegen
2022-10-17  1:01                           ` Heime
2022-10-17  1:15                             ` Michael Heerdegen
2022-10-17  1:01                           ` Stefan Monnier via Users list for the GNU Emacs text editor
2022-10-17  1:22                             ` Michael Heerdegen
2022-10-17  1:27                               ` Michael Heerdegen
2022-10-17  2:08                               ` Heime
2022-10-17  2:42                                 ` Michael Heerdegen
2022-10-17  3:03                                   ` Heime
2022-10-17  3:19                                     ` Emanuel Berg
2022-10-17  1:00                 ` Stefan Monnier via Users list for the GNU Emacs text editor
2022-10-17  1:55                   ` Heime
2022-10-17 12:28                     ` Stefan Monnier
2022-10-17 13:15                       ` Emanuel Berg
2022-10-17 19:27                         ` tomas
2022-10-17 21:32                           ` Emanuel Berg
2022-10-18  0:51                       ` Michael Heerdegen
2022-10-18  1:05                         ` Emanuel Berg
2022-10-16  3:56 ` Stefan Monnier via Users list for the GNU Emacs text editor
2022-10-16  4:00   ` Heime
2022-10-16  4:05     ` Michael Heerdegen
2022-10-16  4:07     ` Stefan Monnier

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).