diff lispref/display.texi @ 52141:a5d4d0a7b284

(Warnings): New node, and subnodes. (Fringes): New node.

--- a/lispref/display.texi	Wed Aug 06 01:21:53 2003 +0000
+++ b/lispref/display.texi	Wed Aug 06 01:23:14 2003 +0000
@@ -15,6 +15,7 @@
 * Forcing Redisplay::   Forcing redisplay.
 * Truncation::          Folding or wrapping long text lines.
 * The Echo Area::       Where messages are displayed.
+* Warnings::            Displaying warning messages for the user.
 * Invisible Text::      Hiding part of the buffer text.
 * Selective Display::   Hiding part of the buffer text (the old way).
 * Overlay Arrow::       Display of an arrow to indicate position.
@@ -23,6 +24,7 @@
 * Width::               How wide a character or string is on the screen.
 * Faces::		A face defines a graphics style for text characters:
                           font, colors, etc.
+* Fringes::             Controlling window fringes.
 * Display Property::    Enabling special display features.
 * Images::              Displaying images in Emacs buffers.
 * Blinking::            How Emacs shows the matching open parenthesis.
@@ -111,10 +113,9 @@
 which is also called @dfn{continuing} the line.  (The display table can
 specify alternative indicators; see @ref{Display Tables}.)
 
-@cindex fringes, and line continuation/truncation indicators
   On a windowed display, the @samp{$} and @samp{\} indicators are
-replaced with graphics bitmaps displayed on the thin areas right near
-the window edges, called the @dfn{fringes}.
+replaced with graphics bitmaps displayed in the window fringes
+(@pxref{Fringes}).
 
   Note that continuation is different from filling; continuation happens
 on the screen only, not in the buffer contents, and it breaks a line
@@ -327,6 +328,194 @@
 If the value is zero, then command input is not echoed.
 @end defvar
 
+@node Warnings
+@section Reporting Warnings
+@cindex warnings
+
+  @dfn{Warnings} are a facility for a program to inform the user of a
+possible problem, but continue running.
+
+@menu
+* Warning Basics::      Warnings concepts and functions to report them.
+* Warning Variables::   Variables programs bind to customize their warnings.
+* Warning Options::     Variables users set to control display of warnings.
+@end menu
+
+@node Warning Basics
+@subsection Warning Basics
+@cindex severity level
+
+  Every warning has a textual message, which explains the problem for
+the user, and a @dfn{severity level} which is a symbol.  Here are the
+possible severity levels, in order of decreasing severity, and their
+meanings:
+
+@table @code
+@item :emergency
+A problem that will seriously impair Emacs operation soon
+if you do not attend to it promptly.
+@item :error
+A report of data or circumstances that are inherently wrong.
+@item :warning
+A report of data or circumstances that are not inherently wrong, but
+raise suspicion of a possible problem.
+@item :debug
+A report of information that may be useful if you are debugging.
+@end table
+
+  When your program encounters invalid input data, it can either
+signal a Lisp error by calling @code{error} or @code{signal} or report
+a warning with severity @code{:error}.  Signaling a Lisp error is the
+easiest thing to do, but it means the program cannot continue
+processing.  If you want to take the trouble to implement a way to
+continue processing despite the bad data, then reporting a warning of
+severity @code{:error} is the right way to inform the user of the
+problem.  For instance, the Emacs Lisp byte compiler can report an
+error that way and continue compiling other functions.  (If the
+program signals a Lisp error and then handles it with
+@code{condition-case}, the user won't see the error message; it could
+show the message to the user by reporting it as a warning.)
+
+@cinedex warning type
+  Each warning has a @dfn{warning type} to classify it.  The type is a
+list of symbols.  The first symbol should be the custom group that you
+use for the program's user options.  For example, byte compiler
+warnings use the warning type @code{(bytecomp)}.  You can also
+subcategorize the warnings, if you wish, by using more symbols in the
+list.
+
+@defun display-warning type message &optional level buffer-name
+This function reports a warning, using @var{message} as the message
+and @var{type} as the warning type.  @var{level} should be the
+severity level, with @code{:warning} being the default.
+
+@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
+for logging the warning.  By default, it is @samp{*Warnings*}.
+@end defun
+
+@defun lwarn type level message &rest args
+This function reports a warning using the value of @code{(format
+@var{message} @var{args}...)} as the message.  In other respects it is
+equivalent to @code{display-warning}.
+@end defun
+
+@defun warn message &rest args
+This function reports a warning using the value of @code{(format
+@var{message} @var{args}...)} as the message, @code{(emacs)} as the
+type, and @code{:warning} as the severity level.  It exists for
+compatibility only; we recommend not using it, because you should
+specify a specific warning type.
+@end defun
+
+@node Warning Variables
+@subsection Warning Variables
+
+  Programs can customize how their warnings appear by binding
+the variables described in this section.
+
+@defvar warning-levels
+This list defines the meaning and severity order of the warning
+severity levels.  Each element defines one severity level,
+and they are arranged in order of decreasing severity.
+
+Each element has the form @code{(@var{level} @var{string}
+@var{function})}, where @var{level} is the severity level it defines.
+@var{string} specifies the textual description of this level.
+@var{string} should use @samp{%s} to specify where to put the warning
+type information, or it can omit the @samp{%s} so as not to include
+that information.
+
+The optional @var{function}, if non-@code{nil}, is a function to call
+with no arguments, to get the user's attention.
+
+Normally you should not change the value of this variable.
+@end defvar
+
+@defvar warning-prefix-function
+If non-@code{nil}, te value is a function to generate prefix text for
+warnings.  Programs can bind the variable to a suitable function.
+@code{display-warning} calls this function with the warnings buffer
+current, and the function can insert text in it.  That text becomes
+the beginning of the warning message.
+
+The function is called with two arguments, the severity level and its
+entry in @code{warning-levels}.  It should return a list to use as the
+entry (this value need not be an actual member of
+@code{warning-levels}).  By constructing this value, the function to
+change the severity of the warning, or specify different handling for
+a given severity level.
+
+If the variable's value is @code{nil} then there is no function
+to call.
+@end defvar
+
+@defvar warning-series
+Programs can bind this variable to @code{t} to say that the next
+warning should begin a series.  When several warnings form a series,
+that means to leave point on the first warning of the series, rather
+than keep move it for each warning so that it appears on the last one.
+The series ends when the local binding is unbound and
+@code{warning-series} becomes @code{nil} again.
+
+The value can also be a symbol with a function definition.  That is
+equivalent to @code{t}, except that the next warning will also call
+the function with no arguments with the warnings buffer current.  The
+function can insert text which will serve as a header for the series
+of warnings.
+
+Once a series has begun, the value is a marker which points to the
+buffer position in the warnings buffer of the start of the series.
+
+The variable's normal value is @code{nil}, which means to handle
+each warning separately.
+@end defvar
+
+@defvar warning-fill-prefix
+When this variable is non-@code{nil}, it specifies a fill prefix to
+use for filling each warning's text.
+@end defvar
+
+@defvar warning-type-format
+This variable specifies the format for displaying the warning type
+in the warning message.  The result of formatting the type this way
+gets included in the message under the control of the string in the
+entry in @code{warning-levels}.  The default value is @code{" (%s)"}.
+If you bind it to @code{""} then the warning type won't appear at
+all.
+@end defvar
+
+@node Warning Options
+@subsection Warning Options
+
+  These variables are used by users to control what happens
+when a Lisp program reports a warning.
+
+@defopt warning-minimum-level
+This user option specifies the minimum severity level that should be
+shown immediately to the user.  The default is @code{:warning}, which
+means to immediately display all warnings except @code{:debug}
+warnings.
+@end defopt
+
+@defopt warning-minimum-log-level
+This user option specifies the minimum severity level that should be
+logged in the warnings buffer.  The default is @code{:warning}, which
+means to log all warnings except @code{:debug} warnings.
+@end defopt
+
+@defopt warning-suppress-types
+This list specifies which warning types should not be displayed
+immediately for the user.  Each element of the list should be a list
+of symbols.  If its elements match the first elements in a warning
+type, then that warning is not displayed immediately.
+@end defopt
+
+@defopt warning-suppress-log-types
+This list specifies which warning types should not be logged in the
+warnings buffer.  Each element of the list should be a list of
+symbols.  If it matches the first few elements in a warning type, then
+that warning is not logged.
+@end defopt
 @node Invisible Text
 @section Invisible Text
 
@@ -572,7 +761,6 @@
 about to be executed.
 
 @defvar overlay-arrow-string
-@cindex fringe, and overlay arrow display
 This variable holds the string to display to call attention to a
 particular line, or @code{nil} if the arrow feature is not in use.
 On a graphical display the contents of the string are ignored; instead a
@@ -2287,6 +2475,54 @@
 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
 field.
 
+@node Fringes
+@section Fringes
+@cindex Fringes
+
+  The @dfn{fringes} of a window are thin vertical strips down the
+sides that are used for displaying bitmaps that indicate truncation,
+continuation, and horizontal scrolling, the overlay arrow.  The
+fringes normally appear between the display margins and the window
+text, but you can put them outside the display margins for a specific
+buffer by setting @code{fringes-outside-margins} buffer-locally to a
+non-@code{nil} value.
+
+@defvar fringes-outside-margins
+If the value is non-@code{nil}, the frames appear outside
+the display margins. 
+@end defvar
+
+@defvar left-fringe-width
+This variable, if non-@code{nil}, specifies the width of the left
+fringe in pixels.
+@end defvar
+
+@defvar right-fringe-width
+This variable, if non-@code{nil}, specifies the width of the right
+fringe in pixels.
+@end defvar
+
+  The values of these variables take effect when you display the
+buffer in a window.  If you change them while the buffer is visible,
+you can call @code{set-buffer-window} to display it in a window again.
+
+@defun set-window-fringes window left &optional right outside-margins
+This function sets the fringe widthes of window @var{window}.
+If window is @code{nil}, that stands for the selected window.
+
+The argument @var{left} specifies the width in pixels of the left
+fringe, and likewise @var{right} for the right fringe.  A value of
+@code{nil} for either one stands for the default width.  If
+@var{outside-margins} is non-@code{nil}, that specifies that fringes
+should appear outside of the display margins.
+@end defun
+
+@defun window-fringes window
+This function returns information about the fringes of a window
+@var{window}.  The value as the form @code{(@var{left-width}
+@var{right-width} @var{frames-outside-margins}).
+@end defun
+
 @node Display Property
 @section The @code{display} Property
 @cindex display specification
@@ -3225,9 +3461,9 @@
 @defopt indicate-empty-lines
 @tindex indicate-empty-lines
 @cindex fringes, and empty line indication
-When this is non-@code{nil}, Emacs displays a special glyph in
-each empty line at the end of the buffer, on terminals that
-support it (window systems).
+When this is non-@code{nil}, Emacs displays a special glyph in the
+fringe of each empty line at the end of the buffer, on terminals that
+support it (window systems).  @xref{Fringes}.
 @end defopt
 
 @defopt tab-width