* Re: describe-mode "some-mode"? [not found] <mailman.7401.1408728471.1147.help-gnu-emacs@gnu.org> @ 2014-08-24 3:39 ` Rusi 2014-08-30 11:36 ` lee 0 siblings, 1 reply; 13+ messages in thread From: Rusi @ 2014-08-24 3:39 UTC (permalink / raw) To: help-gnu-emacs 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 ? ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: describe-mode "some-mode"? 2014-08-24 3:39 ` describe-mode "some-mode"? Rusi @ 2014-08-30 11:36 ` lee 0 siblings, 0 replies; 13+ messages in thread From: lee @ 2014-08-30 11:36 UTC (permalink / raw) To: help-gnu-emacs 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* describe-mode "some-mode"? @ 2014-08-22 17:27 lee 2014-08-22 18:21 ` Drew Adams [not found] ` <mailman.7404.1408731692.1147.help-gnu-emacs@gnu.org> 0 siblings, 2 replies; 13+ messages in thread From: lee @ 2014-08-22 17:27 UTC (permalink / raw) To: help-gnu-emacs 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* RE: describe-mode "some-mode"? 2014-08-22 17:27 lee @ 2014-08-22 18:21 ` Drew Adams 2014-08-23 12:49 ` lee [not found] ` <mailman.7427.1408798399.1147.help-gnu-emacs@gnu.org> [not found] ` <mailman.7404.1408731692.1147.help-gnu-emacs@gnu.org> 1 sibling, 2 replies; 13+ messages in thread From: Drew Adams @ 2014-08-22 18:21 UTC (permalink / raw) To: lee, help-gnu-emacs > 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. ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: describe-mode "some-mode"? 2014-08-22 18:21 ` Drew Adams @ 2014-08-23 12:49 ` lee 2014-08-23 15:29 ` Drew Adams [not found] ` <mailman.7432.1408807808.1147.help-gnu-emacs@gnu.org> [not found] ` <mailman.7427.1408798399.1147.help-gnu-emacs@gnu.org> 1 sibling, 2 replies; 13+ messages in thread From: lee @ 2014-08-23 12:49 UTC (permalink / raw) To: help-gnu-emacs 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* RE: describe-mode "some-mode"? 2014-08-23 12:49 ` lee @ 2014-08-23 15:29 ` Drew Adams 2014-08-30 11:29 ` lee [not found] ` <mailman.7432.1408807808.1147.help-gnu-emacs@gnu.org> 1 sibling, 1 reply; 13+ messages in thread From: Drew Adams @ 2014-08-23 15:29 UTC (permalink / raw) To: lee, help-gnu-emacs > >> 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: describe-mode "some-mode"? 2014-08-23 15:29 ` Drew Adams @ 2014-08-30 11:29 ` lee 0 siblings, 0 replies; 13+ messages in thread From: lee @ 2014-08-30 11:29 UTC (permalink / raw) To: help-gnu-emacs 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
[parent not found: <mailman.7432.1408807808.1147.help-gnu-emacs@gnu.org>]
* Re: describe-mode "some-mode"? [not found] ` <mailman.7432.1408807808.1147.help-gnu-emacs@gnu.org> @ 2014-08-24 1:56 ` Emanuel Berg 2014-08-24 2:46 ` Drew Adams [not found] ` <mailman.7448.1408848386.1147.help-gnu-emacs@gnu.org> 0 siblings, 2 replies; 13+ messages in thread From: Emanuel Berg @ 2014-08-24 1:56 UTC (permalink / raw) To: help-gnu-emacs 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* RE: describe-mode "some-mode"? 2014-08-24 1:56 ` Emanuel Berg @ 2014-08-24 2:46 ` Drew Adams [not found] ` <mailman.7448.1408848386.1147.help-gnu-emacs@gnu.org> 1 sibling, 0 replies; 13+ messages in thread From: Drew Adams @ 2014-08-24 2:46 UTC (permalink / raw) To: Emanuel Berg, help-gnu-emacs > > `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. ^ permalink raw reply [flat|nested] 13+ messages in thread
[parent not found: <mailman.7448.1408848386.1147.help-gnu-emacs@gnu.org>]
* Re: describe-mode "some-mode"? [not found] ` <mailman.7448.1408848386.1147.help-gnu-emacs@gnu.org> @ 2014-08-31 22:27 ` Emanuel Berg 2014-09-01 3:37 ` Drew Adams 0 siblings, 1 reply; 13+ messages in thread From: Emanuel Berg @ 2014-08-31 22:27 UTC (permalink / raw) To: help-gnu-emacs 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* RE: describe-mode "some-mode"? 2014-08-31 22:27 ` Emanuel Berg @ 2014-09-01 3:37 ` Drew Adams 0 siblings, 0 replies; 13+ messages in thread From: Drew Adams @ 2014-09-01 3:37 UTC (permalink / raw) To: Emanuel Berg, help-gnu-emacs > 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. ^ permalink raw reply [flat|nested] 13+ messages in thread
[parent not found: <mailman.7427.1408798399.1147.help-gnu-emacs@gnu.org>]
* Re: describe-mode "some-mode"? [not found] ` <mailman.7427.1408798399.1147.help-gnu-emacs@gnu.org> @ 2014-08-24 2:22 ` Emanuel Berg 0 siblings, 0 replies; 13+ messages in thread From: Emanuel Berg @ 2014-08-24 2:22 UTC (permalink / raw) To: help-gnu-emacs 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
[parent not found: <mailman.7404.1408731692.1147.help-gnu-emacs@gnu.org>]
* Re: describe-mode "some-mode"? [not found] ` <mailman.7404.1408731692.1147.help-gnu-emacs@gnu.org> @ 2014-08-22 19:04 ` Emanuel Berg 0 siblings, 0 replies; 13+ messages in thread From: Emanuel Berg @ 2014-08-22 19:04 UTC (permalink / raw) To: help-gnu-emacs 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2014-09-01 3:37 UTC | newest] Thread overview: 13+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <mailman.7401.1408728471.1147.help-gnu-emacs@gnu.org> 2014-08-24 3:39 ` describe-mode "some-mode"? Rusi 2014-08-30 11:36 ` lee 2014-08-22 17:27 lee 2014-08-22 18:21 ` Drew Adams 2014-08-23 12:49 ` lee 2014-08-23 15:29 ` Drew Adams 2014-08-30 11:29 ` lee [not found] ` <mailman.7432.1408807808.1147.help-gnu-emacs@gnu.org> 2014-08-24 1:56 ` Emanuel Berg 2014-08-24 2:46 ` Drew Adams [not found] ` <mailman.7448.1408848386.1147.help-gnu-emacs@gnu.org> 2014-08-31 22:27 ` Emanuel Berg 2014-09-01 3:37 ` Drew Adams [not found] ` <mailman.7427.1408798399.1147.help-gnu-emacs@gnu.org> 2014-08-24 2:22 ` Emanuel Berg [not found] ` <mailman.7404.1408731692.1147.help-gnu-emacs@gnu.org> 2014-08-22 19:04 ` Emanuel Berg
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.