[Emacs-diffs] emacs/doc/lispref ChangeLog tips.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/04/26 02:35:18

Modified files:
        doc/lispref    : ChangeLog tips.texi 

Log message:
        * tips.texi (Coding Conventions): Copyedits.  Add xref to Named
        Features and Coding System Basics.  Node that "p" stands for
        "predicate".  Recommend utf-8-emacs instead of emacs-mule.
        (Key Binding Conventions): Emacs does use S-down-mouse-1, for
        mouse-appearance-menu.
        (Programming Tips): Add xref to Progress.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/ChangeLog?cvsroot=emacs&r1=1.264&r2=1.265
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/tips.texi?cvsroot=emacs&r1=1.7&r2=1.8

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/ChangeLog,v
retrieving revision 1.264
retrieving revision 1.265
diff -u -b -r1.264 -r1.265
--- ChangeLog   22 Apr 2009 04:21:39 -0000      1.264
+++ ChangeLog   26 Apr 2009 02:35:18 -0000      1.265
@@ -1,3 +1,12 @@
+2009-04-25  Chong Yidong  <address@hidden>
+
+       * tips.texi (Coding Conventions): Copyedits.  Add xref to Named
+       Features and Coding System Basics.  Node that "p" stands for
+       "predicate".  Recommend utf-8-emacs instead of emacs-mule.
+       (Key Binding Conventions): Emacs does use S-down-mouse-1, for
+       mouse-appearance-menu.
+       (Programming Tips): Add xref to Progress.
+
 2009-04-22  Chong Yidong  <address@hidden>
 
        * os.texi (Command-Line Arguments): Document

Index: tips.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/tips.texi,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- tips.texi   9 Apr 2009 01:17:11 -0000       1.7
+++ tips.texi   26 Apr 2009 02:35:18 -0000      1.8
@@ -41,7 +41,7 @@
 
 @itemize @bullet
 @item
-Simply loading the package should not change Emacs's editing behavior.
+Simply loading a package should not change Emacs's editing behavior.
 Include a command or commands to enable and disable the feature,
 or to invoke it.
 
@@ -51,13 +51,14 @@
 don't postpone it.
 
 @item
-Since all global variables share the same name space, and all
-functions share another name space, you should choose a short word to
-distinguish your program from other Lisp address@hidden
-benefits of a Common Lisp-style package system are considered not to
-outweigh the costs.}.  Then take care to begin the names of all global
-variables, constants, and functions in your program with the chosen
-prefix.  This helps avoid name conflicts.
+You should choose a short word to distinguish your program from other
+Lisp programs.  The names of all global variables, constants, and
+functions in your program should begin with that chosen prefix.
+Separate the prefix from the rest of the name with a hyphen, @samp{-}.
+This practice helps avoid name conflicts, since all global variables
+in Emacs Lisp share the same name space, and all functions share
+another name address@hidden benefits of a Common Lisp-style
+package system are considered not to outweigh the costs.}
 
 Occasionally, for a command name intended for users to use, it is more
 convenient if some words come before the package's name prefix.  And
@@ -81,36 +82,32 @@
 If one prefix is insufficient, your package can use two or three
 alternative common prefixes, so long as they make sense.
 
-Separate the prefix from the rest of the symbol name with a hyphen,
address@hidden  This will be consistent with Emacs itself and with most Emacs
-Lisp programs.
-
 @item
 Put a call to @code{provide} at the end of each separate Lisp file.
address@hidden Features}.
 
 @item
 If a file requires certain other Lisp programs to be loaded
 beforehand, then the comments at the beginning of the file should say
 so.  Also, use @code{require} to make sure they are loaded.
address@hidden Features}.
 
 @item
-If one file @var{foo} uses a macro defined in another file @var{bar},
address@hidden should contain this expression before the first use of the
-macro:
+If a file @var{foo} uses a macro defined in another file @var{bar},
+but does not use any functions or variables defined in @var{bar}, then
address@hidden should contain the following expression:
 
 @example
 (eval-when-compile (require '@var{bar}))
 @end example
 
 @noindent
-(And the library @var{bar} should contain @code{(provide '@var{bar})},
-to make the @code{require} work.)  This will cause @var{bar} to be
-loaded when you byte-compile @var{foo}.  Otherwise, you risk compiling
address@hidden without the necessary macro loaded, and that would produce
-compiled code that won't work right.  @xref{Compiling Macros}.
-
-Using @code{eval-when-compile} avoids loading @var{bar} when
-the compiled version of @var{foo} is @emph{used}.
+This tells Emacs to load @var{bar} just before byte-compiling
address@hidden, so that the macro definition is available during
+compilation.  Using @code{eval-when-compile} avoids loading @var{bar}
+when the compiled version of @var{foo} is @emph{used}.  It should be
+called before the first use of the macro in the file.  @xref{Compiling
+Macros}.
 
 @item
 Please don't require the @code{cl} package of Common Lisp extensions at
@@ -132,10 +129,11 @@
 conventions.  @xref{Minor Mode Conventions}.
 
 @item
-If the purpose of a function is to tell you whether a certain condition
-is true or false, give the function a name that ends in @samp{p}.  If
-the name is one word, add just @samp{p}; if the name is multiple words,
-add @samp{-p}.  Examples are @code{framep} and @code{frame-live-p}.
+If the purpose of a function is to tell you whether a certain
+condition is true or false, give the function a name that ends in
address@hidden (which stands for ``predicate'').  If the name is one word,
+add just @samp{p}; if the name is multiple words, add @samp{-p}.
+Examples are @code{framep} and @code{frame-live-p}.
 
 @item
 If the purpose of a variable is to store a single function, give it a
@@ -172,33 +170,26 @@
 @end example
 
 @item
-Redefining (or advising) an Emacs primitive is a bad idea.  It may do
+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 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.
-In the mean time, please don't add any more.
+other programs might break as a result.
 
 @item
-It is likewise a bad idea for one Lisp package to advise a function
-in another Lisp package.
+It is likewise a bad idea for one Lisp package to advise a function in
+another Lisp package (@pxref{Advising Functions}).
 
 @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 a way that's
-not visible in that file.  This is an obstacle for debugging, much
-like advising a function in the other package.
+Avoid using @code{eval-after-load} in libraries and packages
+(@pxref{Hooks for Loading}).  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 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
-standard Emacs, prominent comments at the beginning of the file should
-say which functions are replaced, and how the behavior of the
+If a file does replace any of the standard functions or library
+programs of Emacs, prominent comments at the beginning of the file
+should say which functions are replaced, and how the behavior of the
 replacements differs from that of the originals.
 
 @item
@@ -228,38 +219,23 @@
 @item
 If your program contains non-ASCII characters in string or character
 constants, you should make sure Emacs always decodes these characters
-the same way, regardless of the user's settings.  There are two ways
-to do that:
-
address@hidden -
address@hidden
-Use coding system @code{emacs-mule}, and specify that for
address@hidden in the @samp{-*-} line or the local variables list.
+the same way, regardless of the user's settings.  The easiest way to
+do this is to use the coding system @code{utf-8-emacs} (@pxref{Coding
+System Basics}), and specify that coding in the @samp{-*-} line or the
+local variables list.  @xref{File variables, , Local Variables in
+Files, emacs, The GNU Emacs Manual}.
 
 @example
-;; XXX.el  -*- coding: emacs-mule; -*-
+;; XXX.el  -*- coding: utf-8-emacs; -*-
 @end example
 
 @item
-Use one of the coding systems based on ISO 2022 (such as
address@hidden and iso-2022-7bit), and specify it with @samp{!} at
-the end for @code{coding}.  (The @samp{!} turns off any possible
-character translation.)
-
address@hidden
-;; XXX.el -*- coding: iso-latin-2!; -*-
address@hidden example
address@hidden itemize
-
address@hidden
 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
 default indentation parameters.
 
 @item
-Don't make a habit of putting close-parentheses on lines by themselves;
-Lisp programmers find this disconcerting.  Once in a while, when there
-is a sequence of many consecutive close-parentheses, it may make sense
-to split the sequence in one or two significant places.
+Don't make a habit of putting close-parentheses on lines by
+themselves; Lisp programmers find this disconcerting.
 
 @item
 Please put a copyright notice and copying permission notice on the
@@ -284,7 +260,7 @@
 
 If you have signed papers to assign the copyright to the Foundation,
 then use @samp{Free Software Foundation, Inc.} as @var{name}.
-Otherwise, use your name.  See also @xref{Library Headers}.
+Otherwise, use your name.  @xref{Library Headers}.
 @end itemize
 
 @node Key Binding Conventions
@@ -295,18 +271,18 @@
 @item
 @cindex mouse-2
 @cindex references, following
-Special major modes used for read-only text should usually redefine
address@hidden and @key{RET} to trace some sort of reference in the text.
-Modes such as Dired, Info, Compilation, and Occur redefine it in this
-way.
-
-In addition, they should mark the text as a kind of ``link'' so that
address@hidden will follow it also.  @xref{Clickable Text}.
+Many special major modes, like Dired, Info, Compilation, and Occur,
+are designed to handle read-only text that contains @dfn{hyper-links}.
+Such a major mode should redefine @kbd{mouse-2} and @key{RET} to
+follow the links.  It should also set up a @code{follow-link}
+condition, so that the link obeys @code{mouse-1-click-follows-link}.
address@hidden Text}.  @xref{Buttons}, for an easy method of
+implementing such clickable links.
 
 @item
 @cindex reserved keys
 @cindex keys, reserved
-Please do not define @kbd{C-c @var{letter}} as a key in Lisp programs.
+Don't define @kbd{C-c @var{letter}} as a key in Lisp programs.
 Sequences consisting of @kbd{C-c} and a letter (either upper or lower
 case) are reserved for users; they are the @strong{only} sequences
 reserved for users, so do not block them.
@@ -320,12 +296,6 @@
 also reserved for users to define.
 
 @item
-Applications should not bind mouse events based on button 1 with the
-shift key held down.  These events include @kbd{S-mouse-1},
address@hidden, @kbd{C-S-mouse-1}, and so on.  They are reserved for
-users.
-
address@hidden
 Sequences consisting of @kbd{C-c} followed by a control character or a
 digit are reserved for major modes.
 
@@ -340,13 +310,14 @@
 may be shadowed from time to time by minor modes.
 
 @item
-Do not bind @kbd{C-h} following any prefix character (including
address@hidden).  If you don't bind @kbd{C-h}, it is automatically available
-as a help character for listing the subcommands of the prefix character.
+Don't bind @kbd{C-h} following any prefix character (including
address@hidden).  If you don't bind @kbd{C-h}, it is automatically
+available as a help character for listing the subcommands of the
+prefix character.
 
 @item
-Do not bind a key sequence ending in @key{ESC} except following
-another @key{ESC}.  (That is, it is OK to bind a sequence ending in
+Don't bind a key sequence ending in @key{ESC} except following another
address@hidden  (That is, it is OK to bind a sequence ending in
 @address@hidden @key{ESC}}.)
 
 The reason for this rule is that a non-prefix binding for @key{ESC} in
@@ -420,8 +391,8 @@
 (or @code{signal}).  The function @code{error} does not return.
 @xref{Signaling Errors}.
 
-Do not use @code{message}, @code{throw}, @code{sleep-for},
-or @code{beep} to report errors.
+Don't use @code{message}, @code{throw}, @code{sleep-for}, or
address@hidden to report errors.
 
 @item
 An error message should start with a capital letter but should not end
@@ -479,10 +450,11 @@
 
 @item
 Many commands that take a long time to execute display a message that
-says something like @samp{Operating...} when they start, and change it to
address@hidden when they finish.  Please keep the style of
+says something like @samp{Operating...} when they start, and change it
+to @samp{Operating...done} when they finish.  Please keep the style of
 these messages uniform: @emph{no} space around the ellipsis, and
address@hidden period after @samp{done}.
address@hidden period after @samp{done}.  @xref{Progress}, for an easy way
+to generate such messages.
 
 @item
 Try to avoid using recursive edits.  Instead, do what the Rmail @kbd{e}