3

When I install a new package, more often than not there are variables that I can set - to customise the package. I love customisations, which is why I use Emacs in the first place.

For example, I installed the osx-dictionary package. In the sample configuration, there is a setq statement:

(setq osx-dictionary-dictionary-choice "Apple")

Everyone recognises expresions such as these. This one uses the Apple dictionary as standard for all dictionary queries.

I would like to change some settings for that package, e.g. to use more than one dictionary for the output. I could try a hack, entering a list of dictionaries in the place of "Apple". However, I am hoping that there is maybe a better way (than me extremely inefficiently fumbling around with Lisp code), which finds the variable required within said package to do what I want.

When I use C-h f and begin to type: osx-dictio, to display possible completions, I get the following list:

Possible completions are:
osx-dictionary--get-buffer             osx-dictionary--goto-dictionary
osx-dictionary--list-dictionaries      osx-dictionary--region-or-word
osx-dictionary--search                 osx-dictionary--view-result
osx-dictionary-cli-find-or-recompile   osx-dictionary-mode
osx-dictionary-open-dictionary.app     osx-dictionary-quit
osx-dictionary-read-word               osx-dictionary-recompile
osx-dictionary-search-input            osx-dictionary-search-pointer

that is two per line, 7 lines, so 14 possibilities. These are not mentioned in the package description. If anyone can explain the major differences between those with - and those with -- it might help me. But that is not my point.

Is there a way to find definable variables within any given packages, so as to know how one can customise that package WITHOUT having to go and read through all the actual code? [That is namely a massive task for some packages... I don't want to know how the package works, I just want to install it, optimise it for my needs and get on with my life!]

These customisations are the ones I would like to store in my .emacs file. therefore, the descriptions of what it does and what the possible input values are, e.g. boolean or otherwise, would also be great to have.

I apologise if there is an easy answer that I have overlooked, but after searching around for too long, I have drawn a blank. If this is the case, I shall accept the downvote and delete my question in embarrassment, post-haste!

  • 2
    The variables of packagename-- format are for the package-internal use only and not intended to be modified directly by the user. – Kaushal Modi Oct 14 '15 at 20:45
  • Is the answer maybe that some packages simply lack thorough documentation, and that reading through the code is necessary? I do understand this is open-source, so one cannot assume to have his hand held for everything - I am very grateful that people make there code free to the community! – n1k31t4 Oct 14 '15 at 20:46
  • 3
    The library you are using as an example defines the customization group as osx-dictionary. If you use the M-x customize-group interface, you can see everything the author has intended that the user be able to customize. There are three (3) items in this example. You can also simply type M-x customize and surf through the various groups. – lawlist Oct 14 '15 at 20:49
  • Excellent - thank you. Would you recommend deleting the question (yes, I am embarrassed), or maybe just rewording and shortening it to make it more straight-forward for the next newbie? – n1k31t4 Oct 14 '15 at 20:52
  • 1
    @DexterMorgan osx-dictionary-dictionary-choice now supports a list of dictionaries, such as (setq osx-dictionary-dictionary-choice '("Simplified Chinese" "Apple")). (I have just implemented this). – xuchunyang Oct 15 '15 at 6:59
8

For best results and to avoid gotchas, do not use setq to set option values. Get in the habit of doing one of the following instead:

  • Use M-x customize OPTION, where OPTION is the option name. Change the value and save your change.
  • Use custom-set-variables or customize-set-variable or customize-set-value in your custom-file (preferably) or in your init file (not as good, because it lets Customize mix the code it manages with your hand-coded code).

setq does not carry out any special initialization or update operations that might be necessary for the option. Customize and its functions do that -- the necessary initialization and updating are triggered automatically whenever you set the value using Customize.

In addition, setq does no type-checking -- it ignores :type as well as :set, :initialize, and all the rest of a defcustom definition -- except for the variable value and doc string.

The lack of type-checking is in fact the most common way for users to shoot themselves in the foot by using setq, because the use of :set and :initialize (and other keywords) in defcustoms is not so common. It is fairly common for a user to write an Emacs help question asking what went wrong, where the answer is that s?he used setq and assigned a value of a type that does not respect the type specified by the defcustom. Not the end of the world, but it can be quite puzzling when you pay no attention to what user options are all about. They are not just defvars.


To see all loaded user options (or all that match an input pattern):

  • You can use customize-apropos to customize them.

  • You can use M-x set-variable TAB to see them. And you can use it to set any of them, but like setq, bypassing update triggers.

  • 2
    I am guilty of setting all variables using setq in my init. But I haven't faced any problem with that. Can you please give an example where the variable needs special initialization? – Kaushal Modi Oct 15 '15 at 1:45
  • 2
  • 1
    Downvoted by me because of strong emphasis on "Do not use setq to set option values." which is not true for people not using Customize interface. I have 5k code lines in my init.el with 500 lines containing setq. No errors. I enjoy Emacs daily. You can respond with "Yeah, well, that's just, like, your opinion, man.". Time for hard data: search limited to .init.el* and .emacs files github.com/… gives 50k lines with setq. – kmicu Oct 15 '15 at 19:55
  • 1
    @kmicu: Yes, it is true also for people not using Customize interface. Read what I wrote. Use customize-set-variable or custom-set-variables, neither of which requires you to use the Customize interface. Both of those respect setter and initializer triggers that were defined by the defcustom. And they perform type-checking against the allowable types specified by the defcustom. setq knows nothing about defcustom -- it treats user options the same as any other global variables (it treats defcustom the same as defvar). – Drew Oct 15 '15 at 21:32
  • 1
    @kmicu: And of course you will find plenty of setq occurrences in README and init files. You will find them in my own init file! Not all setq occurrences involve user options. And yes, even for many user options, if the value assigned is of the proper type then using setq or set can be benign. The point is that it is not a good idea to blindly use setq for user options. Sooner or later, doing so will bite you. It is better to get in the habit of using custom-set-variables or customize-set-variable. That's all. Now do as you like... – Drew Oct 15 '15 at 21:47
4

If you want the exact analogue of C-hf, that would be C-hv (being the command describe-variable as opposed to describe-function).

n.b. Type C-hC-h to see all of the C-h bindings (there are a lot, and many of them won't seem useful now, but you should remind yourself what's there every now and again -- some of the "not useful" things may seem rather more useful with the benefit of experience...)


In addition:

  • M-x apropos-user-option describes all user options matching a given pattern.
  • M-x apropos-variable does likewise for all variables (whether or not they are user options).

The difference between a user option and other variables is whether they are defined with defcustom or just defvar. Obviously the two have distinct intended purposes, but it's not necessarily the case that the variables you may wish to configure will all be defined as user options.

n.b. Type C-ha apropos RET to see what other kinds of apropos commands you can use to ask Emacs to tell you useful things. (C-h a being the default binding for apropos-command itself).


To access the customize interface for a given library, you typically1 use M-x customize-group RET LIBRARY RET for the LIBRARY in question. That should give you access to all of the user options of that library.

1 Some libraries may divide their user options amongst various different customize groups -- it's really up to the library in question -- but if the library uses sensible (searchable) names for its variables then, between all the methods shown here, you should find everything on offer.


Note that in all cases above, the results are only for currently-loaded (or perhaps auto-loaded) libraries; so make sure that the features you wish to customize are already loaded before you start asking Emacs about the available options.


And last (but definitely not least), in the manual see:

  • C-hig (emacs) Easy Customization RET
  • C-hig (emacs) Variables RET

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.