X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/9689908391a0630f3e3584af6b7624caa619263e..824974dfa488298ea687eb7b1ba900dbd51079ed:/lispref/tips.texi

diff --git a/lispref/tips.texi b/lispref/tips.texi
index dc1a31545a..d36ef12a08 100644
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -4,28 +4,29 @@
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/tips
 @node Tips, GNU Emacs Internals, Calendar, Top
-@appendix Tips and Standards
+@appendix Tips and Conventions
 @cindex tips
 @cindex standards of coding style
 @cindex coding standards
 
-  This chapter describes no additional features of Emacs Lisp.
-Instead it gives advice on making effective use of the features described
-in the previous chapters.
+  This chapter describes no additional features of Emacs Lisp.  Instead
+it gives advice on making effective use of the features described in the
+previous chapters, and describes conventions Emacs Lisp programmers
+should follow.
 
 @menu
-* Style Tips::                Writing clean and robust programs.
+* Coding Conventions::        Conventions for clean and robust programs.
 * Compilation Tips::          Making compiled code run fast.
 * Documentation Tips::        Writing readable documentation strings.
 * Comment Tips::	      Conventions for writing comments.
 * Library Headers::           Standard headers for library packages.
 @end menu
 
-@node Style Tips
-@section Writing Clean Lisp Programs
+@node Coding Conventions
+@section Emacs Lisp Coding Conventions
 
-  Here are some tips for avoiding common errors in writing Lisp code
-intended for widespread use:
+  Here are conventions that you should follow when writing Emacs Lisp
+code intended for widespread use:
 
 @itemize @bullet
 @item
@@ -84,8 +85,12 @@ Using @code{eval-when-compile} avoids loading @var{bar} when
 the compiled version of @var{foo} is @emph{used}.
 
 @item
-If you define a major mode, make sure to run a hook variable using
-@code{run-hooks}, just as the existing major modes do.  @xref{Hooks}.
+When defining a major mode, please follow the major mode
+conventions.  @xref{Major Mode Conventions}.
+
+@item
+When defining a minor mode, please follow the minor mode
+conventions.  @xref{Minor Mode Conventions}.
 
 @item
 If the purpose of a function is to tell you whether a certain condition
@@ -160,9 +165,9 @@ It is a bad idea to define aliases for the Emacs primitives.  Use the
 standard names instead.
 
 @item
-Redefining an Emacs primitive is an even worse idea.
-It may do the right thing for a particular program, but 
-there is no telling what other programs might break as a result.
+Redefining (or advising) an Emacs primitive is discouraged.  It may do
+the right thing for a particular program, but there is no telling what
+other programs might break as a result.
 
 @item
 If a file does replace any of the functions or library programs of
@@ -248,7 +253,7 @@ coherent if all libraries use the same conventions.
 
 @item
 Try to avoid compiler warnings about undefined free variables, by adding
-@cdode{defvar} definitions for these variables.
+@code{defvar} definitions for these variables.
 
 If you bind a variable in one function, and use it or set it in another
 function, the compiler warns about the latter function unless the
@@ -402,6 +407,12 @@ line.  This looks nice in the source code, but looks bizarre when users
 view the documentation.  Remember that the indentation before the
 starting double-quote is not part of the string!
 
+@item
+When the user tries to use a disabled command, Emacs displays just the
+first paragraph of its documentation string---everything through the
+first blank line.  If you wish, you can choose which information to
+include before the first blank line so as to make this display useful.
+
 @item
 A variable's documentation string should start with @samp{*} if the
 variable is one that users would often want to set interactively.  If
@@ -444,11 +455,11 @@ single-quotes for those symbols.)
 @item
 Don't write key sequences directly in documentation strings.  Instead,
 use the @samp{\\[@dots{}]} construct to stand for them.  For example,
-instead of writing @samp{C-f}, write @samp{\\[forward-char]}.  When
-Emacs displays the documentation string, it substitutes whatever key is
-currently bound to @code{forward-char}.  (This is normally @samp{C-f},
-but it may be some other character if the user has moved key bindings.)
-@xref{Keys in Documentation}.
+instead of writing @samp{C-f}, write the construct
+@samp{\\[forward-char]}.  When Emacs displays the documentation string,
+it substitutes whatever key is currently bound to @code{forward-char}.
+(This is normally @samp{C-f}, but it may be some other character if the
+user has moved key bindings.)  @xref{Keys in Documentation}.
 
 @item
 In documentation strings for a major mode, you will want to refer to the