(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 e7f05587e7..de0294cffa 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,66 @@
+2005-02-26  Richard M. Stallman  <[email protected]>
+
+	* 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  <[email protected]>
 
 	* modes.texi (Defining Minor Modes): Explain that INIT-VALUE,
diff --git a/lispref/tips.texi b/lispref/tips.texi
index 8d7fd5ec5f..c029ee1d45 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