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 bind a variable in one function, and use it or set it in
another function, the compiler warns about the latter function unless
the variable has a definition. But adding a definition would be
-unclean if the variable has a short names, since Lisp packages should
+unclean if the variable has a short name, since Lisp packages should
not define short variable names. The right thing to do is to rename
this variable to start with the name prefix used for the other
functions and variables in your package.
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