More doc updates.

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

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 85c9ac5..fe492df 100644 (file)
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -430,29 +430,35 @@ to what @code{eval-when-compile} does.
 @section Compiler Errors
 @cindex compiler errors
 
-  Byte compilation outputs all errors and warnings into the buffer
-@file{*Compile-Log*}.  The messages include file names and line
-numbers that identify the location of the problem.  The usual Emacs
-commands for operating on compiler diagnostics work properly on these
+  Error and warning messages from byte compilation are printed in a
+buffer named @file{*Compile-Log*}.  These messages include file names
+and line numbers identifying the location of the problem.  The usual
+Emacs commands for operating on compiler output can be used on these
 messages.
 
   When an error is due to invalid syntax in the program, the byte
 compiler might get confused about the errors' exact location.  One way
-to investigate is to switch to the buffer @w{@file{ *Compiler Input*}}.
-(This buffer name starts with a space, so it does not show up in
-@kbd{M-x list-buffers}.)  This buffer contains the program being
+to investigate is to switch to the buffer @w{@file{ *Compiler
+Input*}}.  (This buffer name starts with a space, so it does not show
+up in the Buffer Menu.)  This buffer contains the program being
 compiled, and point shows how far the byte compiler was able to read;
 the cause of the error might be nearby.  @xref{Syntax Errors}, for
 some tips for locating syntax errors.
 
-  When the byte compiler warns about functions that were used but not
-defined, it always reports the line number for the end of the file,
-not the locations where the missing functions were called.  To find
-the latter, you must search for the function names.
+  A common type of warning issued by the byte compiler is for
+functions and variables that were used but not defined.  Such warnings
+report the line number for the end of the file, not the locations
+where the missing functions or variables were used; to find these, you
+must search the file manually.
 
-  You can suppress the compiler warning for calling an undefined
-function @var{func} by conditionalizing the function call on an
-@code{fboundp} test, like this:
+  If you are sure that a warning message about a missing function or
+variable is unjustified, there are several ways to suppress it:
+
+@itemize @bullet
+@item
+You can suppress the warning for a specific call to a function
+@var{func} by conditionalizing it on an @code{fboundp} test, like
+this:
 
 @example
 (if (fboundp '@var{func}) ...(@var{func} ...)...)
@@ -463,14 +469,10 @@ The call to @var{func} must be in the @var{then-form} of the
 @code{if}, and @var{func} must appear quoted in the call to
 @code{fboundp}.  (This feature operates for @code{cond} as well.)
 
-  You can tell the compiler that a function is defined using
-@code{declare-function} (@pxref{Declaring Functions}).  Likewise, you
-can tell the compiler that a variable is defined using @code{defvar}
-with no initial value.
-
-  You can suppress the compiler warning for a specific use of an
-undefined variable @var{variable} by conditionalizing its use on a
-@code{boundp} test, like this:
+@item
+Likewise, you can suppress the warning for a specific use of a
+variable @var{variable} by conditionalizing it on a @code{boundp}
+test:
 
 @example
 (if (boundp '@var{variable}) ...@var{variable}...)
@@ -481,7 +483,17 @@ The reference to @var{variable} must be in the @var{then-form} of the
 @code{if}, and @var{variable} must appear quoted in the call to
 @code{boundp}.
 
-  You can suppress any and all compiler warnings within a certain
+@item
+You can tell the compiler that a function is defined using
+@code{declare-function}. @xref{Declaring Functions}.
+
+@item
+Likewise, you can tell the compiler that a variable is defined using
+@code{defvar} with no initial value.  (Note that this marks the
+variable as special.)  @xref{Defining Variables}.
+@end itemize
+
+  You can also suppress any and all compiler warnings within a certain
 expression using the construct @code{with-no-warnings}:
 
 @c This is implemented with a defun, but conceptually it is
@@ -497,8 +509,9 @@ possible piece of code, to avoid missing possible warnings other than
 one you intend to suppress.
 @end defspec
 
-  More precise control of warnings is possible by setting the variable
-@code{byte-compile-warnings}.
+  Byte compiler warnings can be controlled more precisely by setting
+the variable @code{byte-compile-warnings}.  See its documentation
+string for details.
 
 @node Byte-Code Objects
 @section Byte-Code Function Objects