(Coding Conventions): Clarify.

Put all the major mode key reservations together.
Mention the Mouse-1 => Mouse-2 conventions.

2 files changed, 84 insertions, 23 deletions

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  <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,
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,16 +130,26 @@ 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.
 
@@ -158,10 +164,6 @@ 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
 as a help character for listing the subcommands of the prefix character.
@@ -189,12 +191,6 @@ after @key{ESC}.  In these states, you should define @kbd{@key{ESC}
 @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
 Special major modes used for read-only text should usually redefine
@@ -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