describe-mode "some-mode"?

describe-mode "some-mode"?

[lee]

Hi,

is there a function like describe-key which describes a mode specified
by the user?

The docstring of describe-mode says it either describes the mode of the
current buffer or of the buffer given.  How can I get a description of a
mode without enabling the mode in a buffer?


-- 
GNU Emacs 24.4.50.2 (x86_64-unknown-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2014-08-17 on yun.yagibdah.de

RE: describe-mode "some-mode"?

[Drew Adams]

> is there a function like describe-key which describes a mode specified
> by the user?
> 
> The docstring of describe-mode says it either describes the mode of the
> current buffer or of the buffer given.  How can I get a description of a
> mode without enabling the mode in a buffer?

Something like this will get you started. For more info (e.g. to include minor-mode info) see the definition of `describe-mode'.  You could also improve the interactive spec, to use completion against major modes or something.

(defun my-describe-mode (mode)
  (interactive (list (intern (read-string "Mode: "))))
  (with-help-window (help-buffer)
    (with-current-buffer (help-buffer)
      (insert (help-documentation mode nil 'ADD-HELP-BUTTONS)))))

On the other hand, it is OK and simple to instead create a temporary buffer, put it in the mode, and use `describe-mode' there.

Re: describe-mode "some-mode"?

[lee]

Drew Adams <drew.adams@oracle.com> writes:

>> is there a function like describe-key which describes a mode specified
>> by the user?
>> 
>> The docstring of describe-mode says it either describes the mode of the
>> current buffer or of the buffer given.  How can I get a description of a
>> mode without enabling the mode in a buffer?
>
> Something like this will get you started. For more info (e.g. to include minor-mode info) see the definition of `describe-mode'.  You could also improve the interactive spec, to use completion against major modes or something.
>
> (defun my-describe-mode (mode)
>   (interactive (list (intern (read-string "Mode: "))))
>   (with-help-window (help-buffer)
>     (with-current-buffer (help-buffer)
>       (insert (help-documentation mode nil 'ADD-HELP-BUTTONS)))))

,----
| Compiling file /home/lee/emacs/my-helper-functions.el at Sat Aug 23 14:44:35 2014
| 
| In end of data:
| my-helper-functions.el:116:1:Warning: the function `help-documentation' is not
|     known to be defined.
`----

> On the other hand, it is OK and simple to instead create a temporary buffer, put it in the mode, and use `describe-mode' there.

Yes, I thought about writing a function to do just that and thought it
shouldn't be necessary to create a dummy-buffer to see the docstring for
a particular mode.  Emacs is self-documenting :)

It seems I'd have to do just that for now ...


-- 
GNU Emacs 24.4.50.2 (x86_64-unknown-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2014-08-17 on yun.yagibdah.de

RE: describe-mode "some-mode"?

[Drew Adams]

> >> is there a function like describe-key which describes a mode specified
> >> by the user?
> >>
> >> The docstring of describe-mode says it either describes the mode of the
> >> current buffer or of the buffer given.  How can I get a description of a
> >> mode without enabling the mode in a buffer?
> >
> > Something like this will get you started. For more info (e.g. to include
> > minor-mode info) see the definition of `describe-mode'.  You could also
> > improve the interactive spec, to use completion against major modes or
> > something.
> >
> > (defun my-describe-mode (mode)
> >   (interactive (list (intern (read-string "Mode: "))))
> >   (with-help-window (help-buffer)
> >     (with-current-buffer (help-buffer)
> >       (insert (help-documentation mode nil 'ADD-HELP-BUTTONS)))))
> 
> Warning: the function `help-documentation' is not known to be defined.

My bad.  Sometimes I forget what is provided from emacs -Q and what
is from my code (I should have tested it with emacs -Q).

`help-documentation' is defined in `help-fns+.el'
(http://www.emacswiki.org/emacs-en/download/help-fns%2b.el).  It is
like the vanilla function `documentation', but it uses
`help-substitute-command-keys' so that keys mentioned in the help
become links to their doc.

Using only vanilla functions:

(defun my-describe-mode (mode)
  (interactive (list (intern (read-string "Mode: "))))
  (with-help-window (help-buffer)
    (with-current-buffer (help-buffer)
      (insert (substitute-command-keys (documentation mode))))))

> > On the other hand, it is OK and simple to instead create a temporary
> > buffer, put it in the mode, and use `describe-mode' there.
> 
> Yes, I thought about writing a function to do just that and thought it
> shouldn't be necessary to create a dummy-buffer to see the docstring for
> a particular mode.  Emacs is self-documenting :)
> 
> It seems I'd have to do just that for now ...

(defun my-describe-mode2 (mode)
  (interactive (list (intern (read-string "Mode: "))))
  (with-temp-buffer
    (funcall mode)
    (describe-mode)))

M-x my-describe-mode2 RET emacs-lisp-mode RET

Re: describe-mode "some-mode"?

[lee]

Drew Adams <drew.adams@oracle.com> writes:

>> >> is there a function like describe-key which describes a mode specified
>> >> by the user?
>> >>
>> >> The docstring of describe-mode says it either describes the mode of the
>> >> current buffer or of the buffer given.  How can I get a description of a
>> >> mode without enabling the mode in a buffer?
>> >
>> > Something like this will get you started. For more info (e.g. to include
>> > minor-mode info) see the definition of `describe-mode'.  You could also
>> > improve the interactive spec, to use completion against major modes or
>> > something.
>> >
>> > (defun my-describe-mode (mode)
>> >   (interactive (list (intern (read-string "Mode: "))))
>> >   (with-help-window (help-buffer)
>> >     (with-current-buffer (help-buffer)
>> >       (insert (help-documentation mode nil 'ADD-HELP-BUTTONS)))))
>> 
>> Warning: the function `help-documentation' is not known to be defined.
>
> My bad.  Sometimes I forget what is provided from emacs -Q and what
> is from my code (I should have tested it with emacs -Q).
>
> `help-documentation' is defined in `help-fns+.el'
> (http://www.emacswiki.org/emacs-en/download/help-fns%2b.el).  It is
> like the vanilla function `documentation', but it uses
> `help-substitute-command-keys' so that keys mentioned in the help
> become links to their doc.
>
> Using only vanilla functions:
>
> (defun my-describe-mode (mode)
>   (interactive (list (intern (read-string "Mode: "))))
>   (with-help-window (help-buffer)
>     (with-current-buffer (help-buffer)
>       (insert (substitute-command-keys (documentation mode))))))

Thank you very much, that works fine! :)


-- 
GNU Emacs 24.4.50.2 (x86_64-unknown-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2014-08-17 on yun.yagibdah.de

Re: describe-mode "some-mode"?

[Emanuel Berg]

Drew Adams <drew.adams@oracle.com> writes:

> `help-documentation' is defined in `help-fns+.el'
> (http://www.emacswiki.org/emacs-en/download/help-fns%2b.el).
> It is like the vanilla function `documentation', but
> it uses `help-substitute-command-keys' so that keys
> mentioned in the help become links to their doc.

Why isn't such a helpful feature itself vanilla?

> Using only vanilla functions:
>
> (defun my-describe-mode (mode) (interactive (list
> (intern (read-string "Mode: ")))) (with-help-window
> (help-buffer) (with-current-buffer (help-buffer)
> (insert (substitute-command-keys (documentation
> mode))))))
>
> ...
>
> (defun my-describe-mode (mode) (interactive (list
> (intern (read-string "Mode: ")))) (with-temp-buffer
> (funcall mode) (describe-mode)))

And make one of those vanilla as well!

And then - as it seems only the lowercase m is employed
by the help system, for describing the current buffer
modes:

(global-set-key "\C-hM" 'my-describe-mode)

But, for message-mode, those don't give identical
output for me with respect to the minor modes. Perhaps
Gnus enables something in a hook that is not part of
plain message-mode. So you should be careful separating
when you want to describe a mode in general, and the
mode specifically in effect for the current buffer!

my-describe-mode:

    Enabled minor modes: Abbrev Auto-Composition
    Auto-Fill Global-Font-Lock Shell-Dirtrack
    Show-Paren Transient-Mark

describe-mode:

    Enabled minor modes: Abbrev Auto-Composition
    Auto-Fill Font-Lock Global-Font-Lock
    Gnus-Message-Citation Shell-Dirtrack Show-Paren
    Transient-Mark

-- 
underground experts united

RE: describe-mode "some-mode"?

[Drew Adams]

> > `help-documentation' is defined in `help-fns+.el'
> > (http://www.emacswiki.org/emacs-en/download/help-fns%2b.el).
> > It is like the vanilla function `documentation', but
> > it uses `help-substitute-command-keys' so that keys
> > mentioned in the help become links to their doc.
> 
> Why isn't such a helpful feature itself vanilla?

There are lots of helpful features that are not in vanilla Emacs.
The choice is up to the Emacs maintainers.

(And one person's helpful feature is can be another's PITA.)

> > Using only vanilla functions:...
> 
> And make one of those vanilla as well!
> And then - as it seems only the lowercase m is employed
> by the help system, for describing the current buffer
> modes: (global-set-key "\C-hM" 'my-describe-mode)
> 
> But, for message-mode, those don't give identical
> output for me with respect to the minor modes.

No, they don't - see my first message.
(It has nothing to do with `message-mode'.)
The first one does not try to include minor-mode info.
That's easily added if you want it.

The point was to show that all of this is already available,
even if not in the form of a ready-made command.  The function
`documentation' that you were looking for, is used here, for
instance.

As is typically the case, the elements of what is needed to
cobble together such a "feature" (command) are in the Emacs
code.  E.g., just look at the definition of `describe-mode'.

It often happens that a given user wants a simple command to
do XYZ, while other users don't feel such a need.  And even
the same user might feel like s?he wants an XYZ command/feature
now, especially when new to Emacs (witness the many "How do I
do this `vi' thing in Emacs?"), and s?he might find later that
s?he really does not really need/want it.

How someone interacts with Emacs changes, with time and with
changes to the code s?he uses.  Many users end up making heavy
use of this or that 3rd-party library, which changes how they use
Emacs, sometimes radically.  And core Emacs features change over
time too - usually for the better.

Some features that were practically unusable in the past (or were
at least not used much) have become things that people use all of
the time.  And sometimes all it took was a few tweaks to the UI
to make them more convenient or more powerful.

That is really the power of Emacs: that every Joe & Jane ends up
fiddling with things to slightly improve them.  This often happens
because someone has an itch to scratch.  But Emacs itself deserves
a lot of the credit, because it is an environment conducive to
customization, er, improvement.

> Perhaps Gnus enables something in a hook that is not part of
> plain message-mode. So you should be careful separating
> when you want to describe a mode in general, and the
> mode specifically in effect for the current buffer!

No, see above.  It has nothing to do with Gnus.  The first
command did not bother to include minor-mode info.

Re: describe-mode "some-mode"?

[Emanuel Berg]

Drew Adams <drew.adams@oracle.com> writes:

>> Why isn't such a helpful feature itself vanilla?
>
> There are lots of helpful features that are not in
> vanilla Emacs.

Yes, which is good. But I believe many should be part
of vanilla Emacs, especially those that do things that
can be considered atomic or very general.

Best example I can think of, and one I have mentioned
many times on this list, is the describe-variable-short
here [1]. It echoes the variable's value in the echo
area. Simple as that.

But there are many, many examples I've come across that
are super simple, very atomic and general but
nevertheless seemingly nowhere to be found and Google
don't show any either. Probably so easy that most
people just write it. And after finding nothing, that
is what I do as well!

> The choice is up to the Emacs maintainers.

Yes, of course. 

> (And one person's helpful feature is can be another's
> PITA.)

Only if it gets in the way!

If it doesn't, you are free to use whatever features
you like.

And: Features are good. A bicycle repair shop has all
the tools of the trade. Tools that aren't used
frequently (but still, sometimes) are put on hooks on
the wall. They don't bother anyone but when they are
needed, they are right there.

> No, they don't - see my first message. (It has nothing
> to do with `message-mode'.)

That's what I used to test.

> The first one does not try to include minor-mode
> info. That's easily added if you want it.

I don't have an opinion if they should be included -
probably not, if this is to describe the major mode. I
just thought the functions were identical.

> The point was to show that all of this is already
> available, even if not in the form of a ready-made
> command. The function `documentation' that you were
> looking for, is used here, for instance.

Yeah, well, in a way everything is always available
with programming but now I talk in the sense
"instantly" available, i.e., the existence of such a
command.

> As is typically the case, the elements of what is
> needed to cobble together such a "feature" (command)
> are in the Emacs code. E.g., just look at the
> definition of `describe-mode'.

Yes, I know, I have myself done such thing hundreds of
times. Some of those times it has been called for, but
many times it is to my mind features that are not
specific to me but should be there for everyone. Next
time I come across such a situation, I'll report it to
this list and hopefully someone can tell me if such a
feature exists, if it exists somewhere else (if so, how
to look for it), and if no to both questions, where I
should publish my solution for the next guy around.
Right now, this discussion is a bit hollow because I
don't have such an example. [Read on, I remembered
several writing this.]

> It often happens that a given user wants a simple
> command to do XYZ, while other users don't feel such
> a need.

If a user wants XYZ, and there is already X, Y, and Z,
I don't think XYZ should be added, unless that's the
only use case for X, Y, and Z.

But if the user want W, and W isn't related to the
user's taste or personality - it is just a simple unit
of computation - then it should be added.

There is one `degrees-to-radians' in float-sup.el. But
it is a macro, not a function. I like it a function.
That is super-simple for me to do. But I still think
there should be such a function in vanilla Emacs. Is
it? If not, where should I look for it? If I don't find
it, where should I publish it if I write it?

Here is another example.

(defun yank-pop-back (&optional arg)
  (interactive "*p")
  (yank-pop (if arg (* arg -1) -1)) )

> And core Emacs features change over time too - usually
> for the better.

Yes, of course.

[1] http://user.it.uu.se/~embe8573/conf/emacs-init/help.el

-- 
underground experts united

RE: describe-mode "some-mode"?

[Drew Adams]

> If a user wants XYZ, and there is already X, Y, and Z,
> I don't think XYZ should be added, unless that's the
> only use case for X, Y, and Z.

If you want something added to vanilla Emacs, use
`M-x report-emacs-bug'.  That is for enhancement requests
and bug reports.  It will bring the request to the attention
of Emacs Dev, you will get their response, and the request
or issue will be tracked.

Elispers all around the world (was: Re: describe-mode "some-mode"?)

[Emanuel Berg]

Drew Adams <drew.adams@oracle.com> writes:

> If you want something added to vanilla Emacs, use
> `M-x report-emacs-bug'. That is for enhancement
> requests and bug reports. It will bring the request
> to the attention of Emacs Dev, you will get their
> response, and the request or issue will be tracked.

You don't think that the thousands of Joe Elisp Hackers
all over the world with their .emacs and .gnus and
private libraries; and all the packages in ELPA, MELPA,
and Marmalade; and all the code in the EmacsWiki; and
all the code published on Usenet and listbots and on
the SX sites and other forums - you don't think this
total diaspora could benefit from a more elaborate
review system than `report-emacs-bug'?

-- 
underground experts united

Re: Elispers all around the world (was: Re: describe-mode "some-mode"?)

[Jorge Araya Navarro]

Emanuel Berg writes:

> Drew Adams <drew.adams@oracle.com> writes:
>
>> If you want something added to vanilla Emacs, use
>> `M-x report-emacs-bug'. That is for enhancement
>> requests and bug reports. It will bring the request
>> to the attention of Emacs Dev, you will get their
>> response, and the request or issue will be tracked.
>
> You don't think that the thousands of Joe Elisp Hackers
> all over the world with their .emacs and .gnus and
> private libraries; and all the packages in ELPA, MELPA,
> and Marmalade; and all the code in the EmacsWiki; and
> all the code published on Usenet and listbots and on
> the SX sites and other forums - you don't think this
> total diaspora could benefit from a more elaborate
> review system than `report-emacs-bug'?

Well, that escalated quickly.

-- 
Pax et bonum.
Jorge Araya Navarro.
Diseñador Publicitario, Programador Python y colaborador en Parabola
 GNU/Linux-libre
https://es.gravatar.com/shackr

RE: Elispers all around the world (was: Re: describe-mode "some-mode"?)

[Drew Adams]

> > If you want something added to vanilla Emacs, use
> > `M-x report-emacs-bug'. That is for enhancement
> > requests and bug reports. It will bring the request
> > to the attention of Emacs Dev, you will get their
> > response, and the request or issue will be tracked.
> 
> You don't think that the thousands of Joe Elisp Hackers
> all over the world with their .emacs and .gnus and
> private libraries; and all the packages in ELPA, MELPA,
> and Marmalade; and all the code in the EmacsWiki; and
> all the code published on Usenet and listbots and on
> the SX sites and other forums - you don't think this
> total diaspora could benefit from a more elaborate
> review system than `report-emacs-bug'?

Same advice applies.

If you want your "more elaborate review system" to come
into being to benefit that diaspora, and if you want it to
be available in Emacs itself or to affect anything that is
distributed with GNU Emacs, then `M-x report-emacs-bug' is
the best way to communicate your suggestion about it.

Your suggestion can include code, of course, if you have
some to offer for this.

And if you want that but you have nothing concrete or
specific to request or offer now, and you want to invite
discussion about your incipient idea that might eventually
lead to something real, you can open a thread to discuss
it on emacs-devel@gnu.org, the Emacs development list.

In short, such developments do not fall from the sky.
If you want to affect GNU Emacs then my advice is to
contact those who develop and maintain it.

All of this applies *IF* you care about affecting vanilla
Emacs - see that qualification in the first line you quoted,
above.

Re: Elispers all around the world (was: Re: describe-mode "some-mode"?)

[Emanuel Berg]

Drew Adams <drew.adams@oracle.com> writes:

> All of this applies *IF* you care about affecting
> vanilla Emacs - see that qualification in the first
> line you quoted, above.

No, I don't really care if it is in the vanilla Emacs
or not. It it is good, it would make sense for it to
be. But as long as it is available and easily
integrated it isn't that important. Example: I use
Emacs-W3M and Gnus every day. Gnus is part of Emacs and
Emacs-W3M is not. That doesn't bother me, I can't say.
To me they are as much parts of Emacs. For other people
that might not find Emacs-W3M for this reason or might
run into problems installing/upgrading it, perhaps it
is a problem, I don't know. (Note: What I remember
installing Emacs-W3M is child's play.)

The way I would to it are along the lines:

1. You have a problem.

2. By specifying the problem, you are presented with
   the available solutions to that problem. Some of
   those solutions may be only partial matches, but
   they can be beneficial to you, still.

3. If you don't find a solution, you solve it, but it
   doesn't stop there: you submit your solution and
   describe formally or semi-formally what problem your
   solution aims to solve. So the next time someone
   faces this problem, your solution will be displayed
   at (2).

In time, it'll be clear that most problems only get one
or two solutions that are serious and have passed the
test of time, also receiving the famous distributed
peer-to-peer review to get the last details figured out
and perfected.

In even more time - yes, the most popular solutions
should (most often) be added to vanilla Emacs if they
solve problems that are general in nature. (But this
shouldn't be automatized, of course.)

As an experiment why such a system is beneficial, just
code whatever in Elisp. Then pick a line at random.
Pretend you didn't know how to do that, or that that
function didn't exist. Use Google to search for a
solution. Many times you get Common Lisp or even C
solutions! (And to use Google to find Elisp code -
brr!)

In the AI world, this type of system is called an
expert system. It is usually implemented as a finite
state machine with the transitions based on probability
theory.

-- 
underground experts united

Re: Elispers all around the world (was: Re: describe-mode "some-mode"?)

[Emanuel Berg]

Jorge Araya Navarro <elcorreo@deshackra.com> writes:

> Well, that escalated quickly.

See my reply to Mr. Adams' posts.

It is not just about submitting suggestions, it is
about searching for what you want and then contributing
your suggestions so that not people have to do the same
thing, over and over.

I am not in principle against "reinventing the wheel" -
it may be interesting to do so, and fun - it is more,
you shouldn't have to do it, if and when you don't want
to.

Many, many times have a coded things that I have been
100% sure has been coded many, many times before me.
Sometimes I have not cared to even look: even if I had
been able to find it (not certain), and even if that
would have saved me time (compared to coding it), it is
just so unpleasant to Google for Elisp (and browse
forums with a bunch of morons being angry with each
other, read threads that just stops with no solution,
etc.) - I might as well write it myself.

-- 
underground experts united

Re: describe-mode "some-mode"?

[Emanuel Berg]

lee <lee@yun.yagibdah.de> writes:

> Emacs is self-documenting :)

Emacs has a very clever help system that automatically
incorporates the interfaces as you add functions
(etc.). And, the help system has clever ways of
hyperlinking and accounting for the configurationism of
Emacs users, e.g., you don't "hard-document" actual
keys in docstrings, but the correct keys (for the
particular user, that may have his own keys) turn up
just the same. And more. And the documentation comes
with Emacs. Yes.

But Emacs is still not exactly self-documenting, I
wouldn't say.

Here is an example of a creative docstring: hyperlinked
(to wrap-search); keys (universal-argument will turn up
C-u for most); and, the PREFIX will turn up in the face
help-argument-name.

(defun wrap-search-again (prefix)
  "Search again for the most recent search string of `wrap-search'.
   Use \\[universal-argument] \(to set the PREFIX\) to toggle case sensitiveness."
  ; ...
  )

You can use the below defun to check your docstrings.
It is intended to check the code of packages, but you
can use it to check docstrings and just ignore what it
says that is package-related (if you are not coding a
package, of course).

(defun check-pack-style ()
  (interactive)
  (checkdoc-current-buffer t) ) ; TAKE-NOTES (report all errors)

-- 
underground experts united

Re: describe-mode "some-mode"?

[Emanuel Berg]

Drew Adams <drew.adams@oracle.com> writes:

> On the other hand, it is OK and simple to instead
> create a temporary buffer, put it in the mode, and
> use describe-mode' there.

It is OK, but the OP is right, and that code should be
made official, if there isn't anything else to this
extent.

Isn't there some REPL mode where, like in Clojure, you
can do for example (source n) and (doc name)?

-- 
underground experts united

IELM (was: Re: describe-mode "some-mode"?)

[Emanuel Berg]

Emanuel Berg <embe8573@student.uu.se> writes:

> It is OK, but the OP is right, and that code should
> be made official, if there isn't anything else to
> this extent.
>
> Isn't there some REPL mode where, like in Clojure,
> you can do for example (source n) and (doc name)?

Found it (sort of).

It is `M-x ielm' and then (documentation FUNCTION). It
works only for functions. But faces and variables also
have documentation... There should be a generic such
command!

I didn't find a (source n) equivalent.

Also, the IELM and/or `documentation' doesn't seem to
wrap lines or respect the \n in the docstrings. Makes
it a lot less practical.

-- 
underground experts united

describe-mode "some-mode": (documentation some-mode) (was: IELM)

[lee]

Emanuel Berg <embe8573@student.uu.se> writes:

> Emanuel Berg <embe8573@student.uu.se> writes:
>
>> It is OK, but the OP is right, and that code should
>> be made official, if there isn't anything else to
>> this extent.
>>
>> Isn't there some REPL mode where, like in Clojure,
>> you can do for example (source n) and (doc name)?
>
> Found it (sort of).
>
> It is `M-x ielm' and then (documentation FUNCTION). It
> works only for functions. But faces and variables also
> have documentation... There should be a generic such
> command!
>
> I didn't find a (source n) equivalent.
>
> Also, the IELM and/or `documentation' doesn't seem to
> wrap lines or respect the \n in the docstrings. Makes
> it a lot less practical.


(defun my-describe-mode ()
  "Display the documentation of MODE."
  (interactive)
  (let ((mode (list (intern (read-string "Mode: ")))))
    (unless (functionp mode)
      (with-current-buffer (switch-to-buffer-other-window "my-describe-mode")
	(insert (documentation mode))))))


This inserts "Keyboard macro." into the buffer (without the quotes).
I'm not too sure about what I'm doing here ...

When I use (help-buffer) instead of "my-describe-mode" for a buffer, the
(help-buffer) might be read-only?


-- 
GNU Emacs 24.4.50.2 (x86_64-unknown-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2014-08-17 on yun.yagibdah.de

Re: describe-mode "some-mode": (documentation some-mode) (was: IELM)

[Emanuel Berg]

lee <lee@yun.yagibdah.de> writes:

> (defun my-describe-mode () "Display the documentation
> of MODE." (interactive) (let ((mode (list (intern
> (read-string "Mode: "))))) (unless (functionp mode)
> (with-current-buffer (switch-to-buffer-other-window
> "my-describe-mode") (insert (documentation mode))))))
>
> This inserts "Keyboard macro." into the buffer
> (without the quotes). I'm not too sure about what I'm
> doing here ...

What are you trying to do?

Try: `M-x ielm RET', then type

(documentation 'emacs-lisp-mode)

and hit RET. See that it works except the \n's don't
get respected, so it is all on one/the same line.

I don't think it is wise to fiddle with
`documentation', so probably some wrapper must use
`documentation' to extract the docstring, and then
output it, substituting the \n's for newlines (and
more).

Get back to you on this.

> When I use (help-buffer) instead of
> "my-describe-mode" for a buffer, the (help-buffer)
> might be read-only?

The help buffers are read-only, yes.

-- 
underground experts united

Re: describe-mode "some-mode": (documentation some-mode)

[lee]

Emanuel Berg <embe8573@student.uu.se> writes:

> lee <lee@yun.yagibdah.de> writes:
>
>> (defun my-describe-mode () "Display the documentation
>> of MODE." (interactive) (let ((mode (list (intern
>> (read-string "Mode: "))))) (unless (functionp mode)
>> (with-current-buffer (switch-to-buffer-other-window
>> "my-describe-mode") (insert (documentation mode))))))
>>
>> This inserts "Keyboard macro." into the buffer
>> (without the quotes). I'm not too sure about what I'm
>> doing here ...
>
> What are you trying to do?

I was trying to insert the documentation for a mode into a buffer.

Instead of returning the docstring for the mode, (insert (documentation
mode)) inserts "Keybaord macro." into the buffer with the function I
defined to do this.

I'm wondering why apparently (documentation mode) returns "Keyboard
macro." instead of the docstring ...

>> When I use (help-buffer) instead of
>> "my-describe-mode" for a buffer, the (help-buffer)
>> might be read-only?
>
> The help buffers are read-only, yes.

Ah, interesting:  because when I tried to insert into the help-buffer,
"Keyboard macro." was inserted in the current buffer instead.  That's
why I changed the function to use (switch-to-buffer-other-window
"my-describe-mode") instead.

What's the defined or supposed behaviour of 'insert when the buffer to
insert something into is read-only?


-- 
GNU Emacs 24.4.50.2 (x86_64-unknown-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2014-08-17 on yun.yagibdah.de

Re: describe-mode "some-mode": (documentation some-mode)

[Michael Heerdegen]

lee <lee@yun.yagibdah.de> writes:

> >> (defun my-describe-mode () "Display the documentation
> >> of MODE." (interactive) (let ((mode (list (intern
> >> (read-string "Mode: "))))) (unless (functionp mode)
> >> (with-current-buffer (switch-to-buffer-other-window
> >> "my-describe-mode") (insert (documentation mode))))))
> >>
> >> This inserts "Keyboard macro." into the buffer
> >> (without the quotes). I'm not too sure about what I'm
> >> doing here ...

> Instead of returning the docstring for the mode, (insert (documentation
> mode)) inserts "Keybaord macro." into the buffer with the function I
> defined to do this.
>
> I'm wondering why apparently (documentation mode) returns "Keyboard
> macro." instead of the docstring ...

It doesn't.  You bind `mode' to a list (!) of one element, the function.
You want to bind `mode' to the function itself.  (OTOH, for the
interactive spec, you would want to return a list: the list of read
arguments, which are then bound to the argument variables.)

And then, `unless' should be a `when'.

> What's the defined or supposed behaviour of 'insert when the buffer to
> insert something into is read-only?

Raising an error.

Michael.