mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-10 09:12:15 +00:00
(Warnings): New node, and subnodes.
(Fringes): New node.
This commit is contained in:
parent
46c7a6f087
commit
8a6ca431c7
@ -15,6 +15,7 @@ that Emacs presents to the user.
|
||||
* 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 @@ that Emacs presents to the user.
|
||||
* 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 @@ the rightmost column indicates a line that ``wraps'' onto the next line,
|
||||
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 @@ sequence are echoed immediately.)
|
||||
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 @@ interface to debuggers, the overlay arrow indicates the line of code
|
||||
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 @@ Then, the font specifications for all but Chinese GB2312 characters have
|
||||
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 @@ buffers that do not override it. @xref{Default Value}.
|
||||
@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
|
||||
|
Loading…
Reference in New Issue
Block a user