X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/4c02cf8619e158542d4273bda97231b325c63f19..10412e6312cabf9265acbe32fd3743927038015f:/lispref/tips.texi

diff --git a/lispref/tips.texi b/lispref/tips.texi
index 727ae6918d..3a74aa6271 100644
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -118,8 +118,10 @@ run time.  Use of this package is optional, and it is not part of the
 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
@@ -177,9 +179,9 @@ compatibility issues.
 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.
@@ -192,10 +194,10 @@ in another Lisp package.
 @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
@@ -204,11 +206,14 @@ say which functions are replaced, and how the behavior of the
 replacements differs from that of the originals.
 
 @item
-Avoid using macros that define functions and variables with names that
-are constructed.  It is best for maintenance when the name of the
-function or variable being defined is given explicitly in the source
-code, as the second element of the list---as it is when you use
-@code{defun}, @code{defalias}, @code{defvar} and @code{defcustom}.
+Constructs that define a function or variable should be macros,
+not functions, and their names should start with @samp{def}.
+
+@item
+Macros that define a functions or variables should take the name to be
+defined as the first argument.  That will help various tools find the
+definition automatically.  Avoid constructing the names in the macro
+itself, since that would confuse these tools.
 
 @item
 Please keep the names of your Emacs Lisp source files to 13 characters
@@ -247,6 +252,7 @@ character translation.)
 @example
 ;; XXX.el -*- coding: iso-latin-2!; -*-
 @end example
+@end itemize
 
 @item
 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
@@ -277,8 +283,8 @@ file if you distribute copies.  Use a notice like this one:
 
 ;; You should have received a copy of the GNU General Public
 ;; License along with this program; if not, write to the Free
-;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
-;; MA 02110-1301 USA
+;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301 USA
 @end smallexample
 
 If you have signed papers to assign the copyright to the Foundation,
@@ -696,15 +702,15 @@ use @code{defvar} instead, start the doc string with a @samp{*}.
 
 @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
@@ -730,7 +736,7 @@ have the form (KEY . VALUE).  Here, KEY is ...
 
 @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