From: Richard M. Stallman Date: Sun, 27 Feb 2005 00:16:41 +0000 (+0000) Subject: (Coding Conventions): Clarify. X-Git-Tag: ttn-vms-21-2-B4~2101 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=378d0f8e9027563fd667e90ae6d8f19a3576615d;p=emacs.git (Coding Conventions): Clarify. Put all the major mode key reservations together. Mention the Mouse-1 => Mouse-2 conventions. --- diff --git a/lispref/ChangeLog b/lispref/ChangeLog index e7f05587e71..de0294cffa9 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,66 @@ +2005-02-26 Richard M. Stallman + + * tips.texi (Coding Conventions): Clarify. + Put all the major mode key reservations together. + Mention the Mouse-1 => Mouse-2 conventions. + + * syntax.texi (Syntax Class Table): Clarify. + (Syntax Table Functions): syntax-after moved from here. + (Syntax Table Internals): syntax-after moved to here. + (Parsing Expressions): Update info on number of values + and what's meaningful in the STATE argument. + (Categories): Fix typo. + + * sequences.texi (Arrays): Cleanup. + (Char-Tables): Clarify. + + * processes.texi (Deleting Processes): Cleanups, add xref. + (Subprocess Creation): Explain nil in exec-path. Cleanup. + (Process Information): set-process-coding-system, some args optional. + (Input to Processes): Explain various types for PROCESS args. + Rename them from PROCESS-NAME to PROCESS. + (Signals to Processes): Likewise. + (Decoding Output): Cleanup. + (Query Before Exit): Clarify. + + * os.texi (Startup Summary): Correct the options; add missing ones. + (Terminal Output, Batch Mode): Clarify. + (Flow Control): Node deleted. + + * markers.texi (The Mark): Clarify. + + * macros.texi (Expansion): Cleanup. + (Indenting Macros): indent-spec allows ints, not floats. + + * keymaps.texi (Keymaps): Clarify. + (Format of Keymaps): Update lisp-mode-map example. + (Active Keymaps, Key Lookup): Clarify. + (Changing Key Bindings): Add xref to `kbd'. + (Key Binding Commands, Simple Menu Items): Clarify. + (Mouse Menus, Menu Bar): Clarify. + (Menu Example): Replace print example with menu-bar-replace-menu. + + * help.texi (Documentation Basics): Add function-documentation prop. + + * elisp.texi (Top): Don't refer to Flow Control node. + + * commands.texi (Command Overview): Improve xrefs. + (Adjusting Point): Adjusting point applies to intangible and invis. + (Key Sequence Input): Doc extra read-key-sequence args. + Likewise for read-key-sequence-vector. + + * backups.texi (Rename or Copy): Minor fix. + (Numbered Backups): For version-control, say the default. + (Auto-Saving): make-auto-save-file-name example is simplified. + + * advice.texi (Advising Functions): Don't imply one part of Emacs + should advise another part. Markup changes. + (Defining Advice): Move transitional para. + (Activation of Advice): Cleanup. + Explain if COMPILE is nil or negative. + + * abbrevs.texi (Abbrev Expansion): Clarify, fix typo. + 2005-02-24 Lute Kamstra * modes.texi (Defining Minor Modes): Explain that INIT-VALUE, diff --git a/lispref/tips.texi b/lispref/tips.texi index 8d7fd5ec5fb..c029ee1d451 100644 --- a/lispref/tips.texi +++ b/lispref/tips.texi @@ -46,7 +46,7 @@ variables, constants, and functions in your program with the chosen prefix. This helps avoid name conflicts. This recommendation applies even to names for traditional Lisp -primitives that are not primitives in Emacs Lisp---even to +primitives that are not primitives in Emacs Lisp---such as @code{copy-list}. Believe it or not, there is more than one plausible way to define @code{copy-list}. Play it safe; append your name prefix to produce a name like @code{foo-copy-list} or @code{mylib-copy-list} @@ -101,11 +101,7 @@ 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, for the sake of macros. You do that like this: - -@example -(eval-when-compile (require 'cl)) -@end example +time, with @code{(eval-when-compile (require 'cl))}. @item When defining a major mode, please follow the major mode @@ -134,15 +130,25 @@ follow the naming conventions for hooks. @xref{Hooks}. @item @cindex reserved keys @cindex keys, reserved -Please do not define @kbd{C-c @var{letter}} as a key in your major -modes. 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. +Please do not 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. Changing all the Emacs major modes to respect this convention was a lot of work; abandoning this convention would make that work go to waste, and inconvenience users. Please comply with it. +@item +Function keys @key{F5} through @key{F9} without modifier keys are +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. @@ -157,10 +163,6 @@ character are allocated for minor modes. Using them in a major mode is not absolutely prohibited, but if you do that, the major mode binding may be shadowed from time to time by minor modes. -@item -Function keys @key{F5} through @key{F9} without modifier keys are -reserved for users to define. - @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 @@ -188,12 +190,6 @@ after @key{ESC}. In these states, you should define @kbd{@key{ESC} @key{ESC} @key{ESC}} as the way to escape. Otherwise, define @kbd{@key{ESC} @key{ESC}} instead. -@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 @cindex mouse-2 @cindex references, following @@ -202,6 +198,9 @@ Special major modes used for read-only text should usually redefine 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{Links and Mouse-1}. + @item When a package provides a modification of ordinary Emacs behavior, it is good to include a command to enable and disable the feature, provide a @@ -382,8 +381,7 @@ not to warn about uses of the variable @code{foo} in this file. @item If you use many functions and variables from a certain file, you can add a @code{require} for that package to avoid compilation warnings -for them. It is better if the @code{require} acts only at compile -time. Here's how to do this: +for them. For instance, @example (eval-when-compile @@ -434,7 +432,7 @@ Use a message like this one: 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. +Otherwise, use your name. See also @xref{Library Headers}. @end itemize @node Compilation Tips