(Precalculated Fontification): Don't say that

[gnu-emacs] / lispref / advice.texi

diff --git a/lispref/advice.texi b/lispref/advice.texi
index 2006474fc616cf1ff4abaab187f7a1772dd76fe1..a21bce334486e1621b7e042d2c4d454749563b19 100644 (file)
--- a/lispref/advice.texi
+++ b/lispref/advice.texi
@@ -1,6 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1998, 1999 Free Software Foundation, Inc.
+@c Copyright (C) 1998, 1999, 2002, 2003, 2004,
+@c   2005, 2006 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/advising
 @node Advising Functions, Debugging, Byte Compilation, Top
@@ -8,7 +9,7 @@
 @cindex advising functions
 
   The @dfn{advice} feature lets you add to the existing definition of
-a function, by @dfn{advising the function}.  This is a clean method
+a function, by @dfn{advising the function}.  This is a cleaner method
 for a library to customize functions defined within Emacs---cleaner
 than redefining the whole function.
 
@@ -23,8 +24,20 @@ are not the same thing.
 
   @strong{Usage Note:} Advice is useful for altering the behavior of
 existing calls to an existing function.  If you want the new behavior
-for new calls, or for key bindings, it is cleaner to define a new
-function (or a new command) which uses the existing function.
+for new calls, or for key bindings, you should define a new function
+(or a new command) which uses the existing function.
+
+  @strong{Usage note:} Advising a function can cause confusion in
+debugging, since people who debug calls to the original function may
+not notice that it has been modified with advice.  Therefore, if you
+have the possibility to change the code of that function (or ask
+someone to do so) to run a hook, please solve the problem that way.
+Advice should be reserved for the cases where you cannot get the
+function changed.
+
+  In particular, this means that a file in Emacs should not put advice
+on a function in Emacs.  There are currently a few exceptions to this
+convention, but we aim to correct them.
 
 @menu
 * Simple Advice::           A simple example to explain the basics of advice.
@@ -61,7 +74,8 @@ actually changing or even seeing that definition.  Here is how to do
 this:
 
 @example
-(defadvice previous-line (before next-line-at-end (arg))
+(defadvice previous-line (before next-line-at-end
+                                 (&optional arg try-vscroll))
   "Insert an empty line when moving up from the top line."
   (if (and next-line-add-newlines (= arg 1)
            (save-excursion (beginning-of-line) (bobp)))
@@ -74,8 +88,8 @@ this:
 @code{previous-line}.  This piece of advice is named
 @code{next-line-at-end}, and the symbol @code{before} says that it is
 @dfn{before-advice} which should run before the regular definition of
-@code{previous-line}.  @code{(arg)} specifies how the advice code can
-refer to the function's arguments.
+@code{previous-line}.  @code{(&optional arg try-vscroll)} specifies
+how the advice code can refer to the function's arguments.
 
   When this piece of advice runs, it creates an additional line, in the
 situation where that is appropriate, but does not move point to that