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.)
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
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. ;-)
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?
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
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.
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.
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.