4

I was looking for a way to set the default compile directory in emacs and found a great answer here

However I would like to know how I would ever know about this function without google. Below are the current official sources that I know about that document emacs and elisp.

  1. The emacs manual
  2. The elisp manual
  3. emacs itself M-x describe-function M-x describe-variable

If I know what I am searching for, finding the documentation is easy:

M-x describe-function locate-dominating-file returns 

locate-dominating-file is a compiled Lisp function in ‘files.el’.

(locate-dominating-file FILE NAME)

Look up the directory hierarchy from FILE for a directory containing NAME.
Stop at the first parent directory containing a file NAME,
and return the directory.  Return nil if not found.
Instead of a string, NAME can also be a predicate taking one argument
(a directory) and returning a non-nil value if that directory is the one for
which we’re looking.

The emacs and elisp manual (posted above) do not seem to have locate-dominating-file documented.

Here is my question:

How would I ever discover locate-dominating-file even existed without google? As of right now it seems that for this particular function (locate-dominating-file) the only way I could ever discover it (without google) is to actually open up files.el and become familiar with the source. Is that really the only way or am I missing some other obvious source?

Community
  • 1
  • 1
Shane
  • 657
  • 6
  • 21
  • 1
    Despite what veteran Emacs users will tell you about "ask emacs" ("apropos", "Info-...", describe-function, describe-face, etc.), nothing really compares to the monster machines of Google. Most of the people who will tell you to "ask emacs" already know exactly what it is that they are looking for, and they try to make it sound like it should have been a "no-brainer" -- it is not a "no brainer". I frequently *grep* the Emacs source code and skim through the results until I find what I am looking for. I also do that with the info manuals. I am a 4-year Emacs user, who still uses Google. – lawlist Nov 15 '16 at 20:39
  • I think it should be in the elisp manual. You could raise a documentation bug report for that. In answer, this isn't an easy example. You might have done an apropos function search for "file", but that's a long list, and coming up with the best search term to narrow it down isn't necessarily obvious (assuming you don't happen to think of "dominating"). If "locate" occurs to you, then it's easy. I believe *I* found this function by inspecting code which was exhibiting that behaviour (most likely TAGS-related). – phils Nov 15 '16 at 21:09
  • 1
    @lawlist: I disagree. (1) Asking Emacs is the best place to start. Among other things, it teaches you how to ask Emacs. And that includes finding stuff in the code - including grepping. The more you know about Emacs and its code, the better you can know where to look etc. (2) Advising people to ask Emacs first is not condescending or trying to make questions look stupid or simple. (3) Using Emacs itself to learn about Emacs is smart regardless of one's level of Emacs understanding. (4) It is not about comparing Emacs help to Google. Each tool has its advantages. Emacs does not replace Google. – Drew Nov 15 '16 at 21:12
  • @lawlist Thanks for the response! – Shane Nov 15 '16 at 22:37

2 Answers2

2

Try

M-xapropos do search all list symbols

or

C-h d to search in all doc-strings

Jürgen Hötzel
  • 18,997
  • 3
  • 42
  • 58
2

I think the idea is that a good way to find such things is to look for things that already behave in a similar way to what you want, and then look at their code.

E.g. VC will need to look for .git/.hg/.svn subdirectories to determine if the file is under version control, so you might try to look at the VC code. Or the .dir-locals.el files are similarly looked for in parent directories, so you could look at the code implementing this functionality.

This said, it doesn't always work, but Emacs tries to make it very easy to find and look at the source code of something you see.

Stefan
  • 27,908
  • 4
  • 53
  • 82