* bug#23262: 25.0.90; Doc of `with-eval-after-load' and `eval-after-load'
@ 2016-04-10 18:43 Drew Adams
2016-04-30 23:10 ` Lars Ingebrigtsen
0 siblings, 1 reply; 2+ messages in thread
From: Drew Adams @ 2016-04-10 18:43 UTC (permalink / raw
To: 23262
AFAICT, there was no great need for creating macro
`with-eval-after-load' (and essentially telling users to
prefer it over function `eval-after-load'). The "need"
seems to have been only the fact that some users were not
quoting arguments that they did not want to have
evaluated.
But having done that, whoever did it seems to have dropped
the ball wrt documenting it. At the least, its doc should
refer to `eval-after-load' (and vice versa presumably).
As for the changes that were made to the doc string of
`eval-after-load':
FORM can now be a function, and what it can be is
described before the description of what FILE can be.
These are out of order. (OK, not very important.)
As for the doc in the Elisp manual: `eval-after-load' is no
longer even mentioned, except for these nodes: (1) `Hooks for
Loading`, (2) `Coding Conventions', and (3) `Named Features'.
The doc should be cleaned up to be coherent. And (IMHO) it
_should_ document `eval-after-load' - far more important than
documenting `with-eval-after-load'. Mentioning the latter
does not replace describing the former.
1. Node `Hooks for Loading` says:
Normally, well-designed Lisp programs should not use
'eval-after-load'....
Perhaps it meant to say `with-eval-after-load' here?
If not, why not?
2. Node `Coding Conventions' says:
Avoid using 'eval-after-load' in libraries and packages
(*note Hooks for Loading::). This feature is meant for
personal customizations; using it in a Lisp program is
unclean...
Again, why only `eval-after-load' for such a caution, and
not (also) `with-eval-after-load'?
3. Node `Named Features' says:
The direct effect of calling 'provide' is if not already
in FEATURES then to add FEATURE to the front of that list
and call any 'eval-after-load' code waiting for it (*note
Hooks for Loading::).
Now clearly it is correct to speak of `eval-after-load'
here, and not `with-eval-after-load'. But is the same not
true pretty much everywhere? Ultimately, the _behavior_
is that of `eval-after-load' - `with-eval-after-load' is
only a wrapper.
Finally, the Emacs manual makes no reference to either the
macro or the function, except for this, in node `Foldout':
To use the Foldout package, you can type 'M-x load-library
<RET> foldout <RET>'; or you can arrange for to do that
automatically by putting the following in your init file:
(eval-after-load "outline" '(require 'foldout))
Is that mention appropriate, or should it be removed?
What's so special about library `foldout.el' in this regard?
In GNU Emacs 25.0.90.4 (i686-w64-mingw32)
of 2016-03-20
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
`configure --host=i686-w64-mingw32 --without-dbus
--without-compress-install CFLAGS=-static'
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2016-04-30 23:10 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-04-10 18:43 bug#23262: 25.0.90; Doc of `with-eval-after-load' and `eval-after-load' Drew Adams
2016-04-30 23:10 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.