X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/1e103a7cd8a0210ad6d66d6105192e8ab8df19e5..1df7defd8040839a81909b0eb8f428f6158b2362:/doc/lispref/tips.texi?ds=sidebyside

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 4ba7dd9dfe..d54d91b238 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2012
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
-@node Tips, GNU Emacs Internals, GPL, Top
+@node Tips
 @appendix Tips and Conventions
 @cindex tips for writing Lisp
 @cindex standards of coding style
@@ -120,15 +120,18 @@ library when needed.  This way people who don't use those aspects of
 your file do not need to load the extra library.
 
 @item
-Please don't require the @code{cl} package of Common Lisp extensions at
-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.
+If you need Common Lisp extensions, use the @code{cl-lib} library
+rather than the old @code{cl} library.  The latter does not
+use a clean namespace (i.e., its definitions do not
+start with a @samp{cl-} prefix).  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))}.  That's
+There is no problem with using the @code{cl} package at @emph{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.
+compiler expands them before generating the byte-code.  It is still
+better to use the more modern @code{cl-lib} in this case, though.
 
 @item
 When defining a major mode, please follow the major mode
@@ -457,18 +460,8 @@ Lisp programs.
 
 @itemize @bullet
 @item
-@cindex profiling
-@cindex timing programs
-@cindex @file{elp.el}
-Profile your program with the @file{elp} library.  See the file
-@file{elp.el} for instructions.
-
-@item
-@cindex @file{benchmark.el}
-@cindex benchmarking
-Check the speed of individual Emacs Lisp forms using the
-@file{benchmark} library.  See the functions @code{benchmark-run} and
-@code{benchmark-run-compiled} in @file{benchmark.el}.
+Profile your program, to find out where the time is being spent.
+@xref{Profiling}.
 
 @item
 Use iteration rather than recursion whenever possible.
@@ -640,7 +633,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
@@ -765,16 +758,16 @@ describe the most important commands in your major mode, and then use
 @item
 For consistency, phrase the verb in the first sentence of a function's
 documentation string as an imperative---for instance, use ``Return the
-cons of A and B.'' in preference to ``Returns the cons of A and B@.''
+cons of A and B.@:'' in preference to ``Returns the cons of A and B@.''
 Usually it looks good to do likewise for the rest of the first
 paragraph.  Subsequent paragraphs usually look better if each sentence
 is indicative and has a proper subject.
 
 @item
 The documentation string for a function that is a yes-or-no predicate
-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
+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
@@ -792,13 +785,13 @@ defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
 @item
 Write documentation strings in the active voice, not the passive, and in
 the present tense, not the future.  For instance, use ``Return a list
-containing A and B.'' instead of ``A list containing A and B will be
+containing A and B.@:'' instead of ``A list containing A and B will be
 returned.''
 
 @item
 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
-Instead of, ``Cause Emacs to display text in boldface,'' write just
-``Display text in boldface.''
+Instead of, ``Cause Emacs to display text in boldface'', write just
+``Display text in boldface''.
 
 @item
 Avoid using ``iff'' (a mathematics term meaning ``if and only if''),
@@ -821,7 +814,7 @@ to set, use @code{defcustom}.  @xref{Defining Variables}.
 
 @item
 The documentation string for a variable that is a yes-or-no flag should
-start with words such as ``Non-nil means,'' 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.
 @end itemize