bug#9274: 24.0.50; doc string of `normal-top-level-add-subdirs-to-load-path'

bug#9274: 24.0.50; doc string of `normal-top-level-add-subdirs-to-load-path'

[Drew Adams]

The doc string should say `default-directory', not "current directory".
The latter is confusing because imprecise - it should almost never be
used.  The former lets users use `C-h v' to find out exactly which
directory is meant.
 

FWIW - Sheesh, what a horrible function name!  Should have been called
something like `add-subdirs-to-load-path'.  Or, if you're worried about
calling out which subdirs in the name, `add-normal-subdirs-to-load-path'
or some such.  (But "normal" is not a great choice for naming the
subdirs in question, in any case.)  But "normal-top-level" means nothing
here.
 
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-08-08 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt'
 

bug#9274: 24.0.50; doc string of `normal-top-level-add-subdirs-to-load-path'

[Štěpán Němec]

On Wed, 10 Aug 2011 00:25:34 +0200
Drew Adams wrote:

> FWIW - Sheesh, what a horrible function name!

Indeed.

> Should have been called something like `add-subdirs-to-load-path'.

This is one of the fortunate cases when it's never too late to add a
more reasonable (and discoverable -- the function isn't even documented
in the manual AFAIK) alias.


-- 
Štěpán

bug#9274: 24.0.50; doc string of `normal-top-level-add-subdirs-to-load-path'

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> FWIW - Sheesh, what a horrible function name!  Should have been called
> something like `add-subdirs-to-load-path'.

It's a part of normal-top-level, so it's the perfect name.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#9274: 24.0.50; doc string of `normal-top-level-add-subdirs-to-load-path'

[Drew Adams]

> > FWIW - Sheesh, what a horrible function name!  Should have 
> > been called something like `add-subdirs-to-load-path'.
> 
> It's a part of normal-top-level, so it's the perfect name.

Whatever.  It's part of GNU Emacs Lisp too, so maybe an even more perfect name
would be `gnu-emacs-lisp-normal-top-level-add-subdirs-to-load-path'?

I'm no expert on this, but "normal-top-level" itself seems like a lousy name
(what's normal about it? what are the non-normal top levels?)

BTW, `normal-top-level' rambles on for 5788 chars, including long, expository
comments trying to help make some sense of what's going on - a nearly sure sign
that things could be better organized.  And it is invoked from Lisp in only this
one sexp: (setq top-level (normal-top-level)) - nowhere else.

And I do not see `normal-top-level-add-subdirs-to-load-path' (or
`normal-top-level-add-to-load-path', for that matter) used anywhere in the body
of `normal-top-level'.  In fact, it is called from _no_ Lisp code whatsoever.

In what sense then is `n-t-l-a-s-t-l-p' (whew!) "part of normal-top-level" (an
internal function that doesn't even have a doc string, BTW)?

You will notice that the description (doc string) of `n-t-l-a-s-t-l-p' says
nothing about normal-top-level or even top-level.  If its description is
accurate, then the function name should reflect it, saying what the function
does.

If `normal-top-level' is so important to this function, then surely it should be
mentioned in its description.  Surely that would be more important than adding
this unexplained term to the name.

Anyway, this discussion is peripheral to this bug.  The name is monstrous, but
it is unlikely that it will ever be changed...

bug#9274: 24.0.50; doc string of `normal-top-level-add-subdirs-to-load-path'

[Štěpán Němec]

On Wed, 10 Aug 2011 18:34:46 +0200
Drew Adams wrote:

> Anyway, this discussion is peripheral to this bug.  The name is monstrous, but
> it is unlikely that it will ever be changed...

Why is that unlikely? What's wrong with adding a more sensible alias,
optionally declaring the old name obsolete? Standard procedure, it's
done every now and then.

The question is whether the maintainers acknowledge the problem or not
-- I for one don't use the function even though I've known about it for
some time, but I know people who do use it, and the docstring suggests
general usefulness. One more argument for "it's a lousy name".

-- 
Štěpán

bug#9274: 24.0.50; doc string of `normal-top-level-add-subdirs-to-load-path'

[Drew Adams]

> > Anyway, this discussion is peripheral to this bug.  The 
> > name is monstrous, but it is unlikely that it will ever be changed...
> 
> Why is that unlikely?

I can't really speak to whether it is unlikely or why it would be - I misspoke.
I should have said that my _guess_ is that it is unlikely.

And that guess is not based on any good reason I know of why it should not be
changed. On the contrary...

> What's wrong with adding a more sensible alias,
> optionally declaring the old name obsolete?
> Standard procedure, it's done every now and then.

Sounds good to me. And yes, it is.

> The question is whether the maintainers acknowledge the problem
> or not -- I for one don't use the function even though I've known 
> about it for some time, but I know people who do use it, and the
> docstring suggests general usefulness. One more argument for
> "it's a lousy name".

Same here - on all accounts: Yes, that is the question. I haven't used it. But I
see it called out in recommendations here and there (e.g. the wiki) to users.

bug#9274: 24.0.50; doc string of `normal-top-level-add-subdirs-to-load-path'

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> The doc string should say `default-directory', not "current directory".
> The latter is confusing because imprecise - it should almost never be
> used.  The former lets users use `C-h v' to find out exactly which
> directory is meant.

Fixed, thanks.