[Emacs-diffs] Changes to emacs/lispref/display.texi

[Richard M. Stallman]

Index: emacs/lispref/display.texi
diff -c emacs/lispref/display.texi:1.95 emacs/lispref/display.texi:1.96
*** emacs/lispref/display.texi:1.95     Tue Jul 22 11:25:22 2003
--- emacs/lispref/display.texi  Tue Aug  5 21:23:14 2003
***************
*** 15,20 ****
--- 15,21 ----
  * 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,28 ****
--- 24,30 ----
  * 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,120 ****
  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}.
  
    Note that continuation is different from filling; continuation happens
  on the screen only, not in the buffer contents, and it breaks a line
--- 113,121 ----
  which is also called @dfn{continuing} the line.  (The display table can
  specify alternative indicators; see @ref{Display Tables}.)
  
    On a windowed display, the @samp{$} and @samp{\} indicators are
! 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,332 ****
--- 328,521 ----
  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 address@hidden, 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 address@hidden, 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 address@hidden, 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 address@hidden, 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,578 ****
  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
--- 761,766 ----
***************
*** 2287,2292 ****
--- 2475,2528 ----
  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
+ address@hidden value.
+ 
+ @defvar fringes-outside-margins
+ If the value is address@hidden, the frames appear outside
+ the display margins. 
+ @end defvar
+ 
+ @defvar left-fringe-width
+ This variable, if address@hidden, specifies the width of the left
+ fringe in pixels.
+ @end defvar
+ 
+ @defvar right-fringe-width
+ This variable, if address@hidden, 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 address@hidden, 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,3233 ****
  @defopt indicate-empty-lines
  @tindex indicate-empty-lines
  @cindex fringes, and empty line indication
! When this is address@hidden, Emacs displays a special glyph in
! each empty line at the end of the buffer, on terminals that
! support it (window systems).
  @end defopt
  
  @defopt tab-width
--- 3461,3469 ----
  @defopt indicate-empty-lines
  @tindex indicate-empty-lines
  @cindex fringes, and empty line indication
! When this is address@hidden, 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