Doc updates for several Emacs 24.4 changes.

[bpt/emacs.git] / doc / lispref / tips.texi

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 2e3760e..159938e 100644 (file)
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -223,18 +223,13 @@ only for special-purpose buffers.)  People will find Emacs more
 coherent if all libraries use the same conventions.
 
 @item
-If your program contains non-ASCII characters in string or character
-constants, you should make sure Emacs always decodes these characters
-the same way, regardless of the user's settings.  The easiest way to
-do this is to use the coding system @code{utf-8-emacs} (@pxref{Coding
-System Basics}), and specify that coding in the @samp{-*-} line or the
+The default file coding system for Emacs Lisp source files is UTF-8
+(@pxref{Text Representations}).  In the rare event that your program
+contains characters which are @emph{not} in UTF-8, you should specify
+an appropriate coding system in the source file's @samp{-*-} line or
 local variables list.  @xref{File Variables, , Local Variables in
 Files, emacs, The GNU Emacs Manual}.
 
-@example
-;; XXX.el  -*- coding: utf-8-emacs; -*-
-@end example
-
 @item
 Indent the file using the default indentation parameters.
 
@@ -836,10 +831,10 @@ For example:
 
 @smallexample
 @group
-(setq base-version-list                 ; there was a base
+(setq base-version-list                 ; There was a base
       (assoc (substring fn 0 start-vn)  ; version to which
              file-version-assoc-list))  ; this looks like
-                                        ; a subversion
+                                        ; a subversion.
 @end group
 @end smallexample
 
@@ -877,30 +872,14 @@ strings, though.
 
 @item ;;;
 Comments that start with three semicolons, @samp{;;;}, should start at
-the left margin.  These are used, occasionally, for comments within
-functions that should start at the margin.  We also use them sometimes
-for comments that are between functions---whether to use two or three
-semicolons depends on whether the comment should be considered a
+the left margin.  We use them
+for comments which should be considered a
 ``heading'' by Outline minor mode.  By default, comments starting with
 at least three semicolons (followed by a single space and a
 non-whitespace character) are considered headings, comments starting
-with two or fewer are not.
-
-Another use for triple-semicolon comments is for commenting out lines
-within a function.  We use three semicolons for this precisely so that
-they remain at the left margin.  By default, Outline minor mode does
-not consider a comment to be a heading (even if it starts with at
-least three semicolons) if the semicolons are followed by at least two
-spaces.  Thus, if you add an introductory comment to the commented out
-code, make sure to indent it by at least two spaces after the three
-semicolons.
-
-@smallexample
-(defun foo (a)
-;;;  This is no longer necessary.
-;;;  (force-mode-line-update)
-  (message "Finished with %s" a))
-@end smallexample
+with two or fewer are not.  Historically, triple-semicolon comments have
+also been used for commenting out lines within a function, but this use
+is discouraged.
 
 When commenting out entire functions, use two semicolons.