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

[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

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

[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"?

[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"?

[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"?

[Rusi]

On Friday, August 22, 2014 10:57:24 PM UTC+5:30, lee wrote:
> 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?

[I may be missing something but]
Why not

M-x describe-function RET mode-name

?

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

[lee]

Rusi <rustompmody@gmail.com> writes:

> On Friday, August 22, 2014 10:57:24 PM UTC+5:30, lee wrote:
>> 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?
>
> [I may be missing something but]
> Why not
>
> M-x describe-function RET mode-name

That seems to work as well, thanks :)  I even thought of it briefly and
didn't try ...


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

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