scheme-describe-symbol

scheme-describe-symbol

[Kalle Olavi Niemitalo]

TODO says:

> ** Write scheme-describe-symbol and scheme-describe-object.
> 
> scheme-describe-symbol describes a symbol literally.
> scheme-describe-object describes the object associated with a symbol.

What exactly would scheme-describe-symbol tell the user about the
symbol, other than its name?

How does scheme-describe-object choose the module where it takes
the definition of the symbol?  (Common Lisp has different symbols
in different packages... Guile doesn't.)

Re: scheme-describe-symbol

[Keisuke Nishida]

Kalle Olavi Niemitalo <tosi@ees2.oulu.fi> writes:

> > ** Write scheme-describe-symbol and scheme-describe-object.
> > 
> > scheme-describe-symbol describes a symbol literally.
> > scheme-describe-object describes the object associated with a symbol.
> 
> What exactly would scheme-describe-symbol tell the user about the
> symbol, other than its name?
> 
> How does scheme-describe-object choose the module where it takes
> the definition of the symbol?  (Common Lisp has different symbols
> in different packages... Guile doesn't.)

I haven't thought enough about this yet, but I think there are two
cases where we want to use scheme-describe-*.

1. Find documentation by name.

Guile has documentation in guile-procedures.txt.  We have to search
this file by procedure names.

2. Find documentation by object.

An extreme example:

(define + -)
(+ 1 2)

In this case, we may want to find the documentation of `-' instead of
that of `+'.  We also want to describe slot information if the object
is a GOOPS object.

We could combine these two functions into one command, though.

The module can be decided by searching "(define-module ..." in the
current buffer, as scheme-eval-* does.

GOOPS methods could be described specially, like:

----------------------------------------
`+' is a method.

(+ <integer> <integer>)

  ....

(+ <real> <real>)

  ....

----------------------------------------

There are lots of things to do...

-- Kei

Re: scheme-describe-symbol

[Kalle Olavi Niemitalo]

Keisuke Nishida <kxn30@po.cwru.edu> writes:

> (define + -)
> (+ 1 2)
> 
> In this case, we may want to find the documentation of `-' instead of
> that of `+'.

Must there still be a way to get the documentation of `+'?
If not, we could use `procedure-name':

guile> (define + -)
guile> (procedure-name +)
-

> We could combine these two functions into one command, though.

I believe that would be easier for users.

I have an incomplete `scheme-describe-variable'.  I'll start
hacking it again.

> ----------------------------------------
> `+' is a method.

No, it's a generic function.  ;-)

Re: scheme-describe-symbol

[Kalle Olavi Niemitalo]

Keisuke Nishida <kxn30@po.cwru.edu> writes:

> GOOPS methods could be described specially, like:
> 
> ----------------------------------------
> `+' is a method.
> 
> (+ <integer> <integer>)
> 
>   ....

OW!  I spent the last few hours implementing a generic
`describe-object' with methods for procedures, macros and generic
functions... until I noticed GOOPS has had the functionality all
the time:

guile> (use-modules (oop goops describe))
guile> (describe describe)
describe is a generic function. It's an instance of <generic>.
Methods defined for describe
    Method #<<method> (<method> . <top>) 402b92b0>
        Specializers: <method> <top>
    Method #<<method> (<generic>) 402ad0b8>
        Specializers: <generic>
    Method #<<method> (<class>) 4028b758>
        Specializers: <class>
    Method #<<method> (<object>) 40279b18>
        Specializers: <object>
    Method #<<method> (<procedure>) 401cda48>
        Specializers: <procedure>
    Method #<<method> (<top>) 402e4890>
        Specializers: <top>

I guess I'll use that instead... except `describe' doesn't show
documentation strings.  What would be the best way to add them?

Re: scheme-describe-symbol

[Keisuke Nishida]

Kalle Olavi Niemitalo <tosi@ees2.oulu.fi> writes:

> > (define + -)
> > (+ 1 2)
> > 
> > In this case, we may want to find the documentation of `-' instead of
> > that of `+'.
> 
> Must there still be a way to get the documentation of `+'?

Maybe not...

> > We could combine these two functions into one command, though.
> I believe that would be easier for users.

Right.  One more reason why I thought two commands is to distinguish
function references and variable references; that is, suppose the point
is on `bar' in the following expression:

  (foo bar)
       ^
One may want to search for `foo' when one type C-h f and for `bar'
when one type C-h v.  So I guess we should define one function
`scheme-describe-object' and two commands `scheme-describe-function'
and `scheme-describe-variable'.  How about that?

Also I think it would be a good idea to generalize these help functions.
We could define `mode-describe-function', which calls an appropriate
describe function indirectly according to the current major-mode.  If
one type C-u M-x mode-describe-function, it asks the major-mode to search.

A major-mode can be defined as a class in terms of GOOPS.  We could
define the above functions as generic functions.  I'd like to organize
many concepts in Emacs in terms of OOP.  The current implementation of
Emacs seems very messy to me...

> > `+' is a method.
> 
> No, it's a generic function.  ;-)

What is the difference between a method and a generic function exactly?
A method is each definition in a generic function, maybe?  I guess I
need to study CLOS first...

-- Kei

Re: scheme-describe-symbol

[Keisuke Nishida]

Kalle Olavi Niemitalo <tosi@ees2.oulu.fi> writes:

> OW!  I spent the last few hours implementing a generic
> `describe-object' with methods for procedures, macros and generic
> functions... until I noticed GOOPS has had the functionality all
> the time:

> I guess I'll use that instead... except `describe' doesn't show
> documentation strings.  What would be the best way to add them?

I think we'd better modify the file goops/describe.scm so that it
merges ice-9/doc.scm, though I'm not sure if GOOPS supports docstrings.
Once `describe' comes to display enough information, we can redirect
the output to the Emacs buffer.

Maybe we should discuss this part in the guile mailing list.

Re: scheme-describe-symbol

[Kalle Olavi Niemitalo]

Keisuke Nishida <kxn30@po.cwru.edu> writes:

>   (foo bar)
>        ^
> One may want to search for `foo' when one type C-h f and for `bar'
> when one type C-h v.  So I guess we should define one function
> `scheme-describe-object' and two commands `scheme-describe-function'
> and `scheme-describe-variable'.  How about that?

So the functions would default to different symbols when called
interactively, and would otherwise be identical?  Hmm... I think
I'd prefer using the prefix argument to choose between them.

> Also I think it would be a good idea to generalize these help functions.
> We could define `mode-describe-function', which calls an appropriate
> describe function indirectly according to the current major-mode.  If
> one type C-u M-x mode-describe-function, it asks the major-mode to search.

Oh.  This seems all right.  The completion list for major modes
should only show modes which have their own description
functions, so that short abbreviations (s, e) are unambiguous.

This should be extended to M-:, M-C-x and C-x C-e.

Still... currently, C-h f explains Emacs functions and C-h C-i
explains non-Emacs symbols based on the major mode.  I think this
is a good separation and C-h f should not be used for e.g. C
functions.  If the only Emacs languages are Lisp and Scheme, do
we need a language selection menu?  It would be simpler to have
`describe-function' on C-h f and `scheme-describe' on C-h d.
Except that doesn't solve M-:.

> A major-mode can be defined as a class in terms of GOOPS.  We could
> define the above functions as generic functions.

Would each buffer using the same major mode have its own instance
of the major-mode class?

I guess many buffer-local variables could be moved to slots of
major-mode objects.  And overlays could force their own major
modes in buffer regions... umm... this would require storing
Scheme references in overlays, which we can't do yet.

> A method is each definition in a generic function, maybe?

That's right.

Re: scheme-describe-symbol

[Keisuke Nishida]

Kalle Olavi Niemitalo <tosi@ees2.oulu.fi> writes:

> >   (foo bar)
> >        ^
> > One may want to search for `foo' when one type C-h f and for `bar'
> > when one type C-h v.  So I guess we should define one function
> > `scheme-describe-object' and two commands `scheme-describe-function'
> > and `scheme-describe-variable'.  How about that?
> 
> So the functions would default to different symbols when called
> interactively, and would otherwise be identical?  Hmm... I think
> I'd prefer using the prefix argument to choose between them.

Yes, they would.  I don't think using the prefix argument is easier to
use here.  We use separate commands in Emacs Lisp, and I prefer the same
key bindings as them.  (I could customize them, though.)

> Still... currently, C-h f explains Emacs functions and C-h C-i
> explains non-Emacs symbols based on the major mode.  I think this
> is a good separation and C-h f should not be used for e.g. C
> functions.  If the only Emacs languages are Lisp and Scheme, do
> we need a language selection menu?  It would be simpler to have
> `describe-function' on C-h f and `scheme-describe' on C-h d.
> Except that doesn't solve M-:.

Probably you are right.  A variable in a language other than Lisp or
Scheme cannot have a value within Emacs, so especially describe-variable
may not be useful for those languages...  I would prefer to type C-u M-:
to choose a language (and default is decided by major-mode).

> Would each buffer using the same major mode have its own instance
> of the major-mode class?

Possibly.  We need to discuss this later on.