standard Emacs namespace. If your package loads @code{cl} at run time,
that could cause name clashes for users who don't use that package.
-However, there is no problem with using the @code{cl} package at compile
-time, with @code{(eval-when-compile (require 'cl))}.
+However, there is no problem with using the @code{cl} package at
+compile time, with @code{(eval-when-compile (require 'cl))}. That's
+sufficient for using the macros in the @code{cl} package, because the
+compiler expands them before generating the byte-code.
@item
When defining a major mode, please follow the major mode
Redefining (or advising) an Emacs primitive is a bad idea. It may do
the right thing for a particular program, but there is no telling what
other programs might break as a result. In any case, it is a problem
-for debugging, because the two advised function doesn't do what its
-source code says it does. If the programmer investigating the problem
-is unaware that there is advice on the function, the experience can be
+for debugging, because the advised function doesn't do what its source
+code says it does. If the programmer investigating the problem is
+unaware that there is advice on the function, the experience can be
very frustrating.
We hope to remove all the places in Emacs that advise primitives.
@item
Likewise, avoid using @code{eval-after-load} (@pxref{Hooks for
Loading}) in libraries and packages. This feature is meant for
-personal customizations; using it in a Lisp program is unclean because
-it modifies the behavior of another Lisp file in an invisible way.
-This is an obstacle for debugging, much like advising a function in
-the other package.
+personal customizations; using it in a Lisp program is unclean,
+because it modifies the behavior of another Lisp file in a way that's
+not visible in that file. This is an obstacle for debugging, much
+like advising a function in the other package.
@item
If a file does replace any of the functions or library programs of
@item
The documentation string for a variable that is a yes-or-no flag should
-start with words such as ``Non-nil means@dots{}'', to make it clear that
+start with words such as ``Non-nil means,'' to make it clear that
all non-@code{nil} values are equivalent and indicate explicitly what
@code{nil} and non-@code{nil} mean.
@item
The documentation string for a function that is a yes-or-no predicate
-should start with words such as ``Return t if @dots{}'', to indicate
-explicitly what constitutes ``truth''. The word ``return'' avoids
-starting the sentence with lower-case ``t'', which is somewhat
+should start with words such as ``Return t if,'' to indicate
+explicitly what constitutes ``truth.'' The word ``return'' avoids
+starting the sentence with lower-case ``t,'' which could be somewhat
distracting.
@item
@item
Never change the case of a Lisp symbol when you mention it in a doc
-string. If the symbol's name is @code{foo}, write ``foo'', not
+string. If the symbol's name is @code{foo}, write ``foo,'' not
``Foo'' (which is a different symbol).
This might appear to contradict the policy of writing function