RE: FW: [External] : Re: Native compilation by default?: Was [Re: stats say SBCL is 78 875 % faster than natively compiled Elisp

[Drew Adams]

> > > If you want to load "the most efficient option available", then just
> > > don't specify any extension, and Emacs will load the `.el`, `.elc`,
> > > or `.eln` file according to what it finds.
> >
> > Again, please point that out explicitly (though this
> > one will be familiar to longtime Emacs users, as the
> > same logic has long existed for *.el and *.elc).
> 
> The logic has existed, but none of the doc strings of 'load',
> 'load-file', and 'load-library' says anything about it.  Neither does
> the manual.  What is different here?

I won't argue about it.  I can say that when
I read the doc of those functions (long ago)
I never had any doubt that Emacs "would load
the .el or .elc according to what it finds."

I wasn't aware that the discussion here is
only about doc strings.  Whether, and if so
then which, doc strings should mention this
is an open question.  I was talking about
the doc in general, not just doc strings.

But you also say "neither does the manual".  

To me, the Emacs manual is (and has long been)
very clear about this.  Node `Lisp Libraries'
goes into it, pointing out explicitly which
files (*.el or *.elc) get loaded (priority)
by `load', `load-library', and `load-file'.

And that Emacs-manual text points to the more
detailed text in the Elisp manual, node `How
Programs Do Loading'.

So it's not clear to me what you mean by
"neither does the manual".

If that (or similar) doc in the manuals has
been updated to say what's involved wrt *.el,
*.elc, and *.eln, then great.

In that case, perhaps the user confusion shown
in this thread could have been dispelled just
by pointing to the (updated) manuals?

And perhaps some of the doc about compilation
has been updated similarly?

(It also wouldn't hurt for the doc strings of
the various functions (e.g. `load') to link
to a manual.)

Bottom line: Maybe a little more clarification
would help.  Or else maybe it would have been
enough to point to the doc sections that you
think already clear up the confusion exhibited.
You decide.