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

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

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