@cindex reserved keys
@cindex keys, reserved
Please do not define @kbd{C-c @var{letter}} as a key in your major
-modes. These sequences are reserved for users; they are the
-@strong{only} sequences reserved for users, so do not block them.
+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.
-Instead, define sequences consisting of @kbd{C-c} followed by a control
-character, a digit, or certain punctuation characters. These sequences
-are reserved for major modes.
+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.
-Changing all the Emacs major modes to follow this convention was a lot
-of work. Abandoning this convention would make that work go to waste,
-and inconvenience users.
+@item
+Sequences consisting of @kbd{C-c} followed by a control character or a
+digit are reserved for major modes.
@item
Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
@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
+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
@item
@cindex profiling
@cindex timing programs
-@cindex @file{profile.el}
@cindex @file{elp.el}
-Profile your program with the @file{profile} library or the @file{elp}
-library. See the files @file{profile.el} and @file{elp.el} for
-instructions.
+Profile your program with the @file{elp} library. See the file
+@file{elp.el} for instructions.
@item
Use iteration rather than recursion whenever possible.
longer the case---documentation strings now take up very little space in
a running Emacs.
+@item
+Format the documentation string so that it fits in an Emacs window on an
+80-column screen. It is a good idea for most lines to be no wider than
+60 characters. The first line should not be wider than 67 characters
+or it will look bad in the output of @code{apropos}.
+
+You can fill the text if that looks good. However, rather than blindly
+filling the entire documentation string, you can often make it much more
+readable by choosing certain line breaks with care. Use blank lines
+between topics if the documentation string is long.
+
@item
The first line of the documentation string should consist of one or two
complete sentences that stand on their own as a summary. @kbd{M-x
stand on their own, the result looks bad. In particular, start the
first line with a capital letter and end with a period.
-The documentation string is not limited to one line; use as many lines
-as you need to explain the details of how to use the function or
-variable. Please use complete sentences in the additional lines.
+For a function, the first line should briefly answer the question,
+``What does this function do?'' For a variable, the first line should
+briefly answer the question, ``What does this value mean?''
+
+Don't limit the documentation string to one line; use as many lines as
+you need to explain the details of how to use the function or
+variable. Please use complete sentences for the rest of the text too.
@item
For consistency, phrase the verb in the first sentence of a function's
cons of A and B.'' in preference to ``Returns the cons of A and B@.''
Usually it looks good to do likewise for the rest of the first
paragraph. Subsequent paragraphs usually look better if each sentence
-has a proper subject.
+is indicative and has a proper subject.
@item
Write documentation strings in the active voice, not the passive, and in
@item
Do not start or end a documentation string with whitespace.
-
-@item
-Format the documentation string so that it fits in an Emacs window on an
-80-column screen. It is a good idea for most lines to be no wider than
-60 characters. The first line should not be wider than 67 characters
-or it will look bad in the output of @code{apropos}.
-
-You can fill the text if that looks good. However, rather than blindly
-filling the entire documentation string, you can often make it much more
-readable by choosing certain line breaks with care. Use blank lines
-between topics if the documentation string is long.
@item
@strong{Do not} indent subsequent lines of a documentation string so