GNU bug report logs - #33869
26.1; function locate-dominating-file not documented in elisp manual

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 33869 in the body.
You can then email your comments to 33869 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Adam Porter <adam <at> alphapapa.net>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.1; function locate-dominating-file not documented in elisp manual
Date: Tue, 25 Dec 2018 14:23:51 -0600

The function locate-dominating-file appears to be missing from the elisp
manual.  Interestingly, this was noticed and asked by another user on
another forum:

https://stackoverflow.com/questions/40618516/where-is-locate-dominating-file-documented

I noticed this because just now I was trying to remember the name of the
function, and I kept looking in apropos and the manual for other words
and word lists like "overriding", "find file", "find path", "find
directory", etc.

I finally found it by searching Google for "emacs function find repo
directory", and the second hit was a question on Emacs.StackExchange
that mentioned locate-dominating-file.

Thanks.

Message #8 received at 33869 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Adam Porter <adam <at> alphapapa.net>
Cc: 33869 <at> debbugs.gnu.org
Subject: Re: bug#33869: 26.1;
 function locate-dominating-file not documented in elisp manual
Date: Fri, 28 Dec 2018 10:38:05 +0200

> From: Adam Porter <adam <at> alphapapa.net>
> Date: Tue, 25 Dec 2018 14:23:51 -0600
> 
> The function locate-dominating-file appears to be missing from the elisp
> manual.  Interestingly, this was noticed and asked by another user on
> another forum:
> 
> https://stackoverflow.com/questions/40618516/where-is-locate-dominating-file-documented
> 
> I noticed this because just now I was trying to remember the name of the
> function, and I kept looking in apropos and the manual for other words
> and word lists like "overriding", "find file", "find path", "find
> directory", etc.

If we cannot come up with a phrase or a list of phrases for which
locate-dominating-file might be the hit one looks for, I don't see how
adding this to the ELisp manual could improve the discoverability.
None of those you tried above sound right to me, and I'm hard-pressed
for coming with something that is right.  The guy in the SO discussion
wanted the root of the VC repository, which is just one special case
where this function can help, and happens to have a better answer
(vc-root-dir).  So that discussion doesn't really help.

Thus, please suggest phrases that could serve as index entries for
this function.

> I finally found it by searching Google for "emacs function find repo
> directory", and the second hit was a question on Emacs.StackExchange
> that mentioned locate-dominating-file.

When I try that search, only the first hit is a StackExchange
discussion, and it doesn't mention this function.  What am I missing?

Thanks.

Message #11 received at 33869 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Adam Porter <adam <at> alphapapa.net>, 33869 <at> debbugs.gnu.org
Subject: Re: bug#33869: 26.1; function locate-dominating-file not documented
 in elisp manual
Date: Sun, 13 Oct 2019 00:24:38 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> The function locate-dominating-file appears to be missing from the elisp
>> manual. 

[...]

> If we cannot come up with a phrase or a list of phrases for which
> locate-dominating-file might be the hit one looks for, I don't see how
> adding this to the ELisp manual could improve the discoverability.

I've now documented it right below directory-files-recursively and
cindexed them both with (respectively)

@cindex recursing upwards in directories

@cindex recursing downwards in directories

since they are kinda opposites of each other.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.