0

Pressing the F1 key with a cursor/point at an elisp symbol in code I want to view the *Help* related to this symbol, but pressing F1 does not result in rising the appropriate help buffer.

Is there a way to get the help on a symbol at cursor/point by pressing only F1? How?

Update considering given answers and provided comments:

Inspired by dalanicolais answer below an elisp one-liner providing the basic functionality I have asked for:

(global-set-key(kbd"<f1>")(lambda()(interactive)(describe-symbol(symbol-at-point))))

The problem with the up to now given answers (status 2023-04-06 15:34 ECT) is that these with short code lack appropriate user response in case there is no valid symbol giving the impression that the F1 key does not work and that with the longer code is writing unnecessary messages to the *Message* and the minibuffer.

The reason for the necessity of writing unnecessary messages in case of success in showing help for a symbol is the fact that the function describe-symbol returns 1 no matter if a symbol description was found or not.

In this context the original question leads to the question how to get in elisp code feedback about success/failure in finding HELP for symbol-at-point?

If there is no way (and it seems to be the case excluding fiddling with the elisp and C source code of Emacs) to get this feedback, writing unnecessary messages is the only solution allowing to give the user appropriate feedback about the requested information. Appropriate user feedback has in my eyes much higher priority compared to not messing up the *Message* and the minibuffer with not true statements.

Claudio
  • 410
  • 2
  • 11
  • @NickD : with the updated question the comments became obsolete, so I have deleted mine, so that you can delete yours. – Claudio Apr 06 '23 at 13:00
  • Don't quote lambdas. No need for `#'` (and `'` returns a list, not a function). lambda forms are self-evaluating in Elisp. – Drew Apr 06 '23 at 14:26
  • 1
    @Drew Yes, you are right. Thanks for the hint (I have already updated the code in the question). – Claudio Apr 06 '23 at 14:31

3 Answers3

1

As I am not aware of a solution which does not require executing of some elisp code I suggest to use the below provided code in an Emacs initialization file. It will give on a single F1 keypress the help functionality you asked for:

;; ---------------------------------------------------------------------
;; Show HELP for keyb-shortcuts and symbols:
(setq keyb-seq-examples-demo '( "M-/"  "C-h o" "C-x C-0" ))
(defun hlp-for-term-at-point ()
  "Show HELP info about a text element at current cursor/point position
   Supported text elements: symbols and strings with keyb. sequences"
  (interactive)
  ;; --- cursor/point within a string describing a keyb. sequence?
  (if (and (setq curr-term (thing-at-point 'string t)) (setq curr-keyb-shortcut (kbd (substring curr-term 1 -1))) )  
      (progn
          (message "%s" (concat "no HELP available for:  \"" curr-term "\"  using (describe-key)." ))
          (describe-key curr-keyb-shortcut)
      )
      (message "%s" "No string at point")
  )
  ;; cursor/point within a word describing maybe a symbol?
  (if (setq curr-term (thing-at-point 'symbol))
      (progn 
          (message "%s" (concat "no HELP available for:  \"" curr-term "\"  using (describe-symbol)." ))
          (describe-symbol (intern curr-term))
      )
      (message "%s" "No  symbol  at point")
  )
)
;; Enable <F1> to show HELP for terms under cursor/point :
(global-set-key (kbd "<f1>") 'hlp-for-term-at-point)

The code shows you notifications in the minibuffer and the *Messages* buffer and raises the *Help* buffer on a single F1 keypress.

Please notice that with the binding of F1 though you save a RET keypress on each symbol help request, you loose the access to another HELP options via this key and need for example to use C-h followed by k to get HELP about from keyboard typed key bindings/shortcuts as <F1> isn't an alias for C-h anymore.

The code above supports along elisp symbols also HELP on keyboard shortcuts provided as strings in a format accepted by the Emacs elisp kbd function.

Claudio
  • 410
  • 2
  • 11
  • Both `progn`s look wrong: in a single call, it first says, "showing HELP...", then it says "no HELP available..." and then it either pops up a `*Help*` buffer or it doesn't. Look at the `*Messages*` buffer and you'll see both messages *every time*. The echo area gets overwritten so that you see the "correct" message, but that's no way to write a program - IMO. And with your latest change, you can now get all four messages into the `*Messages*` buffer and both `*Help*` messages (as a key and as a symbol) - *in a single run!* – NickD Apr 06 '23 at 04:36
  • @NickD It seems that writing maybe not true and in case of found help info unnecessary messages is the only solution allowing appropriate user feedback. See the update part of my question for details. – Claudio Apr 06 '23 at 14:16
  • I disagree but I really don't have the time to engage in conversation: sorry. – NickD Apr 06 '23 at 16:09
  • @NickD : no reason for "sorry". It's fully OK if you disagree. Thanks for stating this so short and clearly. This saves time on both sides. In between I am digging in the Emacs elisp source code. It seems to be no other way to master Emacs as writing at least a part of it oneself. – Claudio Apr 06 '23 at 17:39
1

Drew and Nick already provided useful answers, but just to come back to the custom function in your answer, I would just use the following (and also I think for such basic function, docstrings and comments are somewhat redundant)

(defun my-describe-symbol ()
  (interactive)
  (describe-symbol (symbol-at-point)))


(global-set-key (kbd "<f1>") 'my-describe-symbol)
dalanicolai
  • 6,108
  • 7
  • 23
  • The problem with this nice short approach which works perfectly in case there is a valid symbol-at-point is that in case there is no valid symbol the F1 key appears to be dead as the opened `*Help*` buffer stubbornly still shows the previous result. The anyway confusing [back] messages are not visible because added at the bottom of the `*Help*` buffer. Have you tried to use it yourself? If you intended to provide a nice short and compact piece of code addressing the question, why not directly a one-liner? – Claudio Apr 06 '23 at 13:17
  • 1
    Ah okay, it was not clear from your (original) question that you also wanted that 'check' functionality. Anyway, the answer for how to solve that is already within the code of the `describe-symbol` function. So you could just copy the relevant code from that function and design your own custom command. The main point of my answer was that you could just use `symbol-at-point`, instead of what you were using in your own answer. If you have a question about how to design your custom function, then you are welcome to come back here to update your question (we all are willing to answer, of course). – dalanicolai Apr 06 '23 at 14:40
  • See the update to my question for the one-liner. And yes, it seems that there is no way to avoid rewriting the code of `describe-symbol` to get rid of the mess with unnecessary messages in my answer. Thanks for pointing this out. And yes ... answers to all questions are already somewhere within the code (smile). – Claudio Apr 06 '23 at 17:49
  • I am aware of the option to use anonymous functions, but personally I prefer a named function here (but it is quite arbitrary in this case). My point was not to shorten your code, but to show that you could use `symbol-at-point`. Also, I am not saying that you can find answers yourself in the code, but I am pointing out that, in this case, you don't have to reinvent code yourself, because a solution, written by experts, is already available in that function. I could write down the function for you, but I figured that you enjoy studying and writing the code yourself... – dalanicolai Apr 06 '23 at 18:20
  • Yeah ... the initial idea of getting HELP about symbols in code on pure F1 has grown to the idea of a powerful F1 with opening URL-links in the default browser, "visiting" files, explaining keyboard shortcuts (already implemented) and so on. The "experts" ... hmmm ... where are they? Probably at stackoverflow or using sublime having no time for "cheap" solutions like Emacs. – Claudio Apr 06 '23 at 18:41
  • And yes ... helping out with code is welcome, but helping to understand the core idea (if there is any ... maybe there isn't?) behind the code even much more. But for the latter one need some very deep understanding oneself. And there is a very huge difference between only knowing how to code something and the ability to explain it to the maid. Excellent code needs as good as no explanations. Building upon a mess does. – Claudio Apr 06 '23 at 18:52
  • I think I need to meditate a little on your comments... – dalanicolai Apr 06 '23 at 19:52
0
(global-set-key (kbd "<f1>") #'describe-symbol)

But note that that takes away using <f1> as a prefix help key.

And note that by default you already have <f1> o bound to describe-symbol.

Drew
  • 75,699
  • 9
  • 109
  • 225
  • Notice that you don't need the `#` in `#'describe-symbol` as `'describe-symbol will be already properly recognized in elisp as a function. The proposed approach requires in case of success in finding the help for the word at point at least an additional return and it confuses with asking for a symbol input when there is no help for the word at point available. – Claudio Apr 06 '23 at 00:30
  • @Claudio You might like to have a look at the answers [here](https://emacs.stackexchange.com/questions/74457/melpa-package-ebib-does-not-appear-on-the-package-list) (and note who wrote those :) – dalanicolai Apr 06 '23 at 11:44
  • @dalanicolai I suppose the link in your comment is not that one you wanted it to be (copy/paste "typo"?). And if it is, how do it relate to my question? – Claudio Apr 06 '23 at 12:52
  • 1
    Ah, you're right, that's sloppy. So I meant the answers at https://emacs.stackexchange.com/a/35989/26163 – dalanicolai Apr 06 '23 at 14:26
  • @Claudio: “When function-object is a symbol and the code is byte compiled, the byte-compiler will warn if that function is not defined or might not be known at run time.” I don't know how Emacs byte compiles file yet, but it seems like a good choice, too, that using a function special form if you intend to use the symbol as a function name. – shynur Apr 06 '23 at 19:20