code intended for widespread use:
@itemize @bullet
+@item
+Simply loading the package should not change Emacs's editing behavior.
+Include a command or commands to enable and disable the feature,
+or to invoke it.
+
+This convention is mandatory for any file that includes custom
+definitions. If fixing such a file to follow this convention requires
+an incompatible change, go ahead and make the incompatible change;
+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
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}
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
@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.
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
@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
Modes such as Dired, Info, Compilation, and Occur redefine it in this
way.
-@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
-command named @code{@var{whatever}-mode} which turns the feature on or
-off, and make it autoload (@pxref{Autoload}). Design the package so
-that simply loading it has no visible effect---that should not enable
-the feature.@footnote{Consider that the package may be loaded
-arbitrarily by Custom for instance.} Users will request the feature by
-invoking the command. It is a good idea to define this command
-as a minor mode.
+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}.
@cindex unloading packages
If loading the file adds functions to hooks, define a function
@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
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
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}.
+
@item
Use iteration rather than recursion whenever possible.
Function calls are slow in Emacs Lisp even when a compiled function