# HG changeset patch # User Chong Yidong # Date 1240713318 0 # Node ID f688a3c7a4ed0a445e60924804176ce8f0c36084 # Parent 1fe870379d8e57e0caf37525c862303fa0d5dab7 * 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. diff -r 1fe870379d8e -r f688a3c7a4ed doc/lispref/ChangeLog --- a/doc/lispref/ChangeLog Sun Apr 26 01:39:48 2009 +0000 +++ b/doc/lispref/ChangeLog Sun Apr 26 02:35:18 2009 +0000 @@ -1,3 +1,12 @@ +2009-04-25 Chong Yidong + + * 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 * os.texi (Command-Line Arguments): Document diff -r 1fe870379d8e -r f688a3c7a4ed doc/lispref/tips.texi --- a/doc/lispref/tips.texi Sun Apr 26 01:39:48 2009 +0000 +++ b/doc/lispref/tips.texi Sun Apr 26 02:35:18 2009 +0000 @@ -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 programs@footnote{The -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 space@footnote{The 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, -@samp{-}. 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. +@xref{Named 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. +x@xref{Named Features}. @item -If one file @var{foo} uses a macro defined in another file @var{bar}, -@var{foo} 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 +@var{foo} 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 -@var{foo} 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 +@var{foo}, 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 +@samp{p} (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. +other programs might break as a result. -We hope to remove all the places in Emacs that advise primitives. -In the mean time, please don't add any more. +@item +It is likewise a bad idea for one Lisp package to advise a function in +another Lisp package (@pxref{Advising Functions}). @item -It is likewise a bad idea for one Lisp package to advise a function -in another Lisp 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 -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. - -@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: - -@itemize - -@item -Use coding system @code{emacs-mule}, and specify that for -@code{coding} 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 -iso-8859-@var{n} and iso-2022-7bit), and specify it with @samp{!} at -the end for @code{coding}. (The @samp{!} turns off any possible -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 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 -@kbd{mouse-2} 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 -@kbd{mouse-1} 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}. +@xref{Clickable 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}, -@kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for -users. - -@item 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 -@kbd{C-c}). 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 +@kbd{C-c}). 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 +@key{ESC}. (That is, it is OK to bind a sequence ending in @kbd{@key{ESC} @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 +@code{beep} 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 -@samp{Operating...done} 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 -@emph{no} period after @samp{done}. +@emph{no} 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}