Commit 378d0f8e authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

(Coding Conventions): Clarify.

Put all the major mode key reservations together.
Mention the Mouse-1 => Mouse-2 conventions.
parent 8a2f014e
2005-02-26 Richard M. Stallman <rms@gnu.org>
* 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 <lute@gnu.org>
* modes.texi (Defining Minor Modes): Explain that INIT-VALUE,
......
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment