0

Thru another post: Add Save as button to org mode toolbar I was happy to get a solution:

    (tool-bar-add-item-from-menu 'write-file "save" nil
                     :label "Save As")

And I wanted to look up the documentation on the syntax of this command because I do not understand what the nil is used for.

The only reference I could find is:

https://doc.endlessparentheses.com/Fun/tool-bar-add-item-from-menu.html

My questions are:

  1. I personally find it very hard to find any good emacs or org mode based documentation on many commands. I have spent a lot of time searching for how to add a toolbar item before I posted asking about how to do so, but did not find anything such as docs explaining each command, syntax, parameters, examples, tutorials, etc. Am I missing something? Am I just looking in the wrong place? Or is the documentation not the greatest?

  2. In the only reference that I could find:

https://doc.endlessparentheses.com/Fun/tool-bar-add-item-from-menu.html

The syntax is described as:

    (tool-bar-add-item-from-menu COMMAND ICON &optional MAP &rest PROPS)

But I have not been able to find a description of &optional, MAP, &rest, and PROPS. Is there some other documentation anywhere where I could start to learn this?

  1. In the command:
    (tool-bar-add-item-from-menu 'write-file "save" nil

what is the nil for?

2
  • 2
    Did you try C-h f tool-bar-add-item-from-menu? Your first reaction on dealing with such questions should be: Ask Emacs!. Learning to use the Help system and the Info manuals is much more productive than endless googling.
    – NickD
    Jul 5 at 14:36
  • Only one question per post, please. Essentially this question is about how to Ask Emacs, I think. The rest is maybe food for posting other questions.
    – Drew
    Jul 7 at 17:37

3 Answers 3

2

How do I find documentation?

As I mentioned in the comment: Ask Emacs!. Emacs has wonderful documentation (as @Tyler describes in his answer), but equally importantly, it provides methods to search and read that documentation effectively and efficiently.

The Help system can be accessed with the C-h prefix: if you do C-h ?, you'll get a list of keys that you can use to get help, e.g. f will give you help on functions, v does the same for variables. I would highly recommend that you go through each and every one of those keys to get an idea of what's available.

Emacs also provides the Info system for reading and searching the manuals: doing C-h i will give you a list of the manuals that are installed on your system. The first manual I would read would be the Info manual itself: say C-h i m Info and have at it. To quote myself: "Learning to use the Help system and the Info manuals is much more productive than endless googling." @Tyler points out two other, very important manuals: the Emacs manual and the Emacs Lisp manual. However, instead of reading them on the web, I would recommend that you read them in Emacs itself: say C-h i g(emacs) or C-h i g(elisp) to go to the indicated manual, then use the stuff you learnt from the Info manual to find your way around each of the other manuals.

What does &optional and &rest and map and props mean?

When the help system shows the syntax of the function to be (tool-bar-add-item-from-menu COMMAND ICON &optional MAP &rest PROPS) , that tells you that the function takes two mandatory arguments (COMMAND and ICON), a third optional argument (MAP) and, starting from the fourth position, an arbitrary number of other arguments which are grouped together in a list (PROPS). All of this is explained in the section of the Emacs Lisp manual entitled "Features of Argument Lists" which you can get to with C-h i g(elisp)argument list. The doc string of the function that you get with C-h f tool-bar-add-item-from-menu tells you that the function does the following:

Define tool bar binding for COMMAND in keymap MAP using the given ICON.
This makes a binding for COMMAND in ‘tool-bar-map’, copying its
binding from the menu bar in MAP (which defaults to ‘global-map’), but
modifies the binding by adding an image specification for ICON.  It
finds ICON just like ‘tool-bar-add-item’.  PROPS are additional
properties to add to the binding.

Now, command is a symbol that refers to an (ahem) command, i.e. a function with an interactive spec. The doc string does not tell you that, but given a bit of experience (i.e. knowing that there is something called a command in Emacs Lisp), you can guess what it is. The only surefire way to know however is to find more documentation for it. You can try the Emacs Manual with C-h i g(emacs)i tool-bar-add-item-from-menu but that doesn't give us anything, so try the Elisp manual instead with C-h i g(elisp)i tool-bar-add-item-from-menu. You'll end up in the same "Tool Bar" section that @Tyler pointed you to above, but instead of reading it in the browser, you'll be reading it in Emacs.

Here are ways to use Info to get to the sections of the Elisp manual that @Tyler provides links to above. First get into the Elisp manual with C-h i g(elisp). Once you are in a manual, then navigation within that manual does not require that initial C-h i g(elisp).

  • keymaps: m keymaps
  • menu keymaps: i menu-k<TAB> - note that there is TAB completion.
  • tool bars: i tool-b<TAB>'

But as @Tyler implies, this example is more complicated than many other functions, because it assumes that you know something about keymaps and menus and tool bars and just uses those concepts without explanation. To use a (possibly bad) analogy: if you don't know much about calculus, then trying to calculate the area of a circle with an integral is probably not a good way to go about learning the subject: you'd start with simpler examples (e.g finding the area under a parabola between some limits).

What is the nil for?

As explained above, the nil in the call is the third argument, so it corresponds to the map argument: the function is called with a null keymap. If there was nothing following, you could leave it out: it's an optional argument. However, there is something following: a property (i.e a pair of items: a property name and a property value), and since you want that to be associated with the props argument, you need to make sure to specify a value for the map argument as well. If you didn't include the nil: (tool-bar-add-item-menu command icon :label "foo") then the third argument is the :label symbol and that would be bound to map, leaving only "foo" for the props argument: confusion would reign and you'd probably end up with an error.

5
  • 2
    We must have a canonical "how to use the info system help/manuals" question/answer here somewhere? If not, the start of your answer, and some of mine, could be the start of one.
    – Tyler
    Jul 6 at 13:32
  • Hi NickD thanks very much for explaining about the documentation. I just never thought about first going to the Help system within emacs but should have. I am so used to searching for things on the Net.
    – ironfish
    Jul 7 at 0:59
  • @NickD as you say "this example is more complicated than many other functions, because it assumes that you know something about keymaps and menus and tool bars and just uses those concepts without explanation." I dont know about keymaps and menus and tool bars etc so this is a bit overwhelming......but I will try and look into it. In any case thank you for taking so much time to provide your input and help.
    – ironfish
    Jul 7 at 1:02
  • PS I think that both Tyler and NickD provided great answers about the documentation, but I see I can vote only one as the answer. Not sure what to do here....
    – ironfish
    Jul 7 at 1:04
  • I did not explain this clearly but I meant I just wanted to know what nil does in the sense of how it affects the Save as command - does it eg change how a file is saved, the format of the file, etc. I am concerned it may affect how the file is saved so that I may have issues with that later on.
    – ironfish
    Jul 7 at 1:20
2

Emacs comes with two extensive manuals (and more besides), accessible via C-h i. For information about interacting with Emacs as a user, the Emacs manual (accessible from Emacs via C-h r) covers most features that are built in to Emacs. For information about the elisp language, and extending Emacs, the Emacs Lisp (C-h i elisp) manual is the canonical source.

Both manuals are enormous, which can be a bit intimidating to newcomers. I recommend skimming through the table of contents to get an idea of what's there, and to target your reading to bits of particular interest.

In the case of toolbars, modifying these is part of extending emacs, so it is in the elisp manual, not the user manual. It's not obvious that they're part of the keymap system, but knowing that you can find the official documentation in that section. You'll probably want to familiarize yourself with keymaps, and menus, as pre-requisites to applying that knowledge to tool bars.

4
  • Thanks Tyler for pointing out the manuals, etc. I am so used to searching for things on the internet that it skipped my mind to look eg under Help lol....
    – ironfish
    Jul 7 at 0:55
  • PS I think that both Tyler and NickD provided great answers about the documentation, but I see I can vote only one as the answer. Not sure what to do here..
    – ironfish
    Jul 7 at 1:04
  • @ironfish: Maybe pick the one that you feel (1) helps you the most with this question or (2) helps other readers the most. Besides giving some "points" to the answer you pick, it can make that answer more findable by other people who might have a similar question.
    – Drew
    Jul 7 at 17:34
  • @ironfish you can give upvotes to any answer you find helpful. Pick whichever one you like best for the checkmark. And you can always change your mind and switch your selection later. This is a very low-stakes decision, just have fun.
    – Tyler
    Jul 7 at 19:21
1

I was the one who answered your original question

... and I was also the one who DID NOT ANSWER the subsequent question

... and it looks like you very much want to revel under a fire hose!

Nevermind.

You will get what you asked for.


Here is a visual explanation of what is happening. Try to follow the arrow, and make the connections.

A visual explanation for tool-bar-add-item-from-menu


The above visual is saying that ...

When MAP is NIL it looks for write-file command under a <menu-bar> key in global-map, and transfers that to tool-bar-map together with an icon.

Put another away, you can replace NIL with global-map in (tool-bar-add-item-from-menu 'write-file "save" nil :label "Save As") call, and the behaviour will be exactly the same.

The doc also says that the MAP you use should have an entry for <menu-bar>. Not all key maps have a <menu-bar> entry.

You can convince yourself that global-map has a menu-bar entry by doing this

(lookup-key global-map [menu-bar])

or that write-file command is reachable through menu-bar in global-map.

(where-is-internal 'write-file (lookup-key global-map [menu-bar]))

As an added exercise, try doing M-x pp-eval-expression RET global-map RET and try to locate menu-bar, write-file entries etc. in the resulting buffer. Then, try to arrive at a mental map of what goes in to a key map.

Hint: In *Pp Eval Output*, C-s write-file RET C-M-u C-M-u C-M-u C-M-u. Remember to pause after each C-M-u and see ponder about what you are looking at vis-a-vis what you know from the menu bar entries.


As one more exercise, based on what you have read above, make a guess on what will happen when you do this

(tool-bar-add-item-from-menu 'yank "paste" nil :label "YANK")

and this

(tool-bar-add-item-from-menu 'clipboard-yank "paste" nil :label "CLIPBOARD YANK")

Can you explain the observed behaviour?

5
  • Not knowing elisp it will take me a long time to learn all the concepts you are talking about. I feel absolutely overwhelmed. And I am not sure if I am willing to invest that time. I was more wondering what the nil did - ie what changes does it make to the Save as command.
    – ironfish
    Jul 7 at 0:52
  • ... and it looks like you very much want to revel under a fire hose! Nevermind. You will get what you asked for. < This sounds like maybe you are annoyed at my question a bit. Is that correct? That is how I am feeling about it.
    – ironfish
    Jul 7 at 0:54
  • whitetrillium: As NickD says "But as @Tyler implies, this example is more complicated than many other functions, because it assumes that you know something about keymaps and menus and tool bars and just uses those concepts without explanation. To use a (possibly bad) analogy: if you don't know much about calculus, then trying to calculate the area of a circle with an integral is probably not a good way to go about learning the subject" This is exactly how I feel about the answer.
    – ironfish
    Jul 7 at 1:07
  • I did not explain this clearly but I meant I just wanted to know what nil does in the sense of how it affects the Save as command - does it eg change how a file is saved, the format of the file, etc...
    – ironfish
    Jul 7 at 1:08
  • Clicking on the Toolbar invokes the command. The Icon is just a visual indicator, and has no relation to what the command is. So, you can use the "saveas" icon, but have the command do something else. The name on the label is no guaranteed of what is inside the box. The label could say "Candy", but the envelope may actually contain Anthrax. Who knows .... only the sender knows. I showed you that while using the same icon, you can use exporting to ascii, write file etc.. For your purposes, use NIL. Jul 7 at 2:43

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.