bug#58364: [PATCH] Add new function 'file-name-parent-p'

[Drew Adams <drew.adams@oracle.com>]

> For apropos, how about changing the doc string to say this instead:
> 
>   Return non-nil if DIR is a parent directory of FILE.
>   Value is non-nil if FILE is inside DIR or inside a subdirectory of
>   DIR.  A directory is considered to be a "parent" of itself.

This is what's wrong with talking loosely about
a file being "inside" a directory - confusion.

The function is called `file-in-directory-p',
where you expect "in" to mean _either_ "inside"
DIR _or_ "inside" a subdir of DIR.  And does
"subdir" here mean a child of DIR or a
descendent of DIR?

Right away, this introduces confusion.  What
does it mean to be "inside" DIR - does it mean
be directly in DIR?  Or does it mean be directly
in either DIR or a directory that's a descendent
of DIR?

If you mean the latter then it makes no sense
to add "or inside a subdirectory of DIR", since
anything "in" any "subdir" of DIR is in that
case also "in" DIR.

And then there's the first doc-string line:

  ...DIR is a parent directory of FILE.

This is wrong.  The predicate apparently tests
whether DIR is an _ancestor_ directory; it
doesn't test whether it's a _parent_ directory.

In some languages "parent" can mean "ancestor"
or even "relative".  But not in English.

And this leaves aside the problem of whether
you really want to say that a _directory_ is a
parent of a _file_.  A dir _contains_ files.
Do you want to also say that a dir is a parent
or ancestor of a file?  (And this has nothing
to do with the fact that a directory itself is
also a file.)

The predicate is about an ancestor-descendent
relation, not a parent-child relation.

And it's really about such a relation between
the directory that FILE is contained in
directly and DIR - that is, it's more precise
not to speak of a directory being a parent or
an ancestor of a file.  (But if you want to
skip over that distinction, that could be OK.)

The predicate name is maybe less important
than getting the doc to be correct.  But
there's really no reason they can't both be 
accurate.

And if Emacs starts using accurate terminology
here then search, completion, apropos etc.
will be more helpful.

And the manual's Index can still offer (also)
entries that are less than accurate, as some
users may well think of a term like "parent"
before they think of "ancestor".  That
possibility isn't a reason not to use more
accurate terms in the doc (in particular), or
even in the function name.

https://en.wikipedia.org/wiki/Ancestor

https://stackoverflow.com/a/10993384/729907

https://stackoverflow.com/questions/55607027/git-what-is-the-logical-difference-between-parent-and-ancestor

https://stackoverflow.com/a/54889445/729907

https://sebastian.expert/ancestor-descendant-sibling-parent-child-explained/

https://teamtreehouse.com/community/what-is-the-difference-between-an-ancestor-and-parent-how-do-ancestors-parents-and-child-elements-relate

https://www.wwp.northeastern.edu/outreach/seminars/_current/presentations/xslt_intro/xpath_intro_tutorial_08.xhtml

https://wp-qa.com/what-is-the-difference-between-current_page_parent-and-current_page_ancestor

https://wikidiff.com/ancestor/parent