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

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 9274 in the body.
You can then email your comments to 9274 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: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; doc string of `normal-top-level-add-subdirs-to-load-path'
Date: Tue, 9 Aug 2011 15:25:34 -0700

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'
 

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

From: Štěpán Němec <stepnem <at> gmail.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 9274 <at> debbugs.gnu.org
Subject: Re: bug#9274: 24.0.50;
	doc string of `normal-top-level-add-subdirs-to-load-path'
Date: Wed, 10 Aug 2011 01:11:38 +0200

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

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

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 9274 <at> debbugs.gnu.org
Subject: Re: bug#9274: 24.0.50;
	doc string of `normal-top-level-add-subdirs-to-load-path'
Date: Wed, 10 Aug 2011 18:02:29 +0200

"Drew Adams" <drew.adams <at> 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 <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Andreas Schwab'" <schwab <at> linux-m68k.org>
Cc: 9274 <at> debbugs.gnu.org
Subject: RE: bug#9274: 24.0.50;
	doc string of `normal-top-level-add-subdirs-to-load-path'
Date: Wed, 10 Aug 2011 09:34:46 -0700

> > 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...

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

From: Štěpán Němec <stepnem <at> gmail.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 'Andreas Schwab' <schwab <at> linux-m68k.org>, 9274 <at> debbugs.gnu.org
Subject: Re: bug#9274: 24.0.50;
	doc string of `normal-top-level-add-subdirs-to-load-path'
Date: Wed, 10 Aug 2011 20:57:25 +0200

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

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Štepán Nemec'" <stepnem <at> gmail.com>
Cc: 'Andreas Schwab' <schwab <at> linux-m68k.org>, 9274 <at> debbugs.gnu.org
Subject: RE: bug#9274: 24.0.50;
	doc string of `normal-top-level-add-subdirs-to-load-path'
Date: Wed, 10 Aug 2011 14:37:54 -0700

> > 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.

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

From: Chong Yidong <cyd <at> stupidchicken.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 9274 <at> debbugs.gnu.org
Subject: Re: bug#9274: 24.0.50;
	doc string of `normal-top-level-add-subdirs-to-load-path'
Date: Sat, 20 Aug 2011 15:30:04 -0400

"Drew Adams" <drew.adams <at> 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.

Previous Next

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