@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
-@c 2002, 2005 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
@node Display, System Interface, Processes, Top
* Refresh Screen:: Clearing the screen and redrawing everything on it.
* Forcing Redisplay:: Forcing redisplay.
* Truncation:: Folding or wrapping long text lines.
-* The Echo Area:: Where messages are displayed.
+* The Echo Area:: Displaying messages at the bottom of the screen.
* Warnings:: Displaying warning messages for the user.
-* Progress:: Informing user about progress of a long operation.
* Invisible Text:: Hiding part of the buffer text.
* Selective Display:: Hiding part of the buffer text (the old way).
* Temporary Displays:: Displays that go away automatically.
* Images:: Displaying images in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
* Blinking:: How Emacs shows the matching open parenthesis.
-* Inverse Video:: Specifying how the screen looks.
* Usual Display:: The usual conventions for displaying nonprinting chars.
* Display Tables:: How to specify other conventions.
* Beeping:: Audible signal to the user.
@cindex error display
@cindex echo area
-The @dfn{echo area} is used for displaying error messages
+ The @dfn{echo area} is used for displaying error messages
(@pxref{Errors}), for messages made with the @code{message} primitive,
and for echoing keystrokes. It is not the same as the minibuffer,
despite the fact that the minibuffer appears (when active) in the same
the minibuffer for use of that screen space (@pxref{Minibuffer,, The
Minibuffer, emacs, The GNU Emacs Manual}).
-You can write output in the echo area by using the Lisp printing
-functions with @code{t} as the stream (@pxref{Output Functions}), or as
-follows:
+ You can write output in the echo area by using the Lisp printing
+functions with @code{t} as the stream (@pxref{Output Functions}), or
+explicitly.
+
+@menu
+* Displaying Messages:: Explicitly displaying text in the echo area.
+* Progress:: Informing user about progress of a long operation.
+* Logging Messages:: Echo area messages are logged for the user.
+* Echo Area Customization:: Controlling the echo area.
+@end menu
+
+@node Displaying Messages
+@subsection Displaying Messages in the Echo Area
+
+ This section describes the functions for explicitly producing echo
+area messages. Many other Emacs features display messages there, too.
@defun message string &rest arguments
This function displays a message in the echo area. The
its normal size. If the minibuffer is active, this brings the
minibuffer contents back onto the screen immediately.
-@vindex message-truncate-lines
-Normally, displaying a long message resizes the echo area to display
-the entire message. But if the variable @code{message-truncate-lines}
-is non-@code{nil}, the echo area does not resize, and the message is
-truncated to fit it, as in Emacs 20 and before.
-
@example
@group
(message "Minibuffer depth is %d."
depending on its size, use @code{display-message-or-buffer} (see below).
@end defun
-@defopt max-mini-window-height
-This variable specifies the maximum height for resizing minibuffer
-windows. If a float, it specifies a fraction of the height of the
-frame. If an integer, it specifies a number of lines.
-@end defopt
-
@tindex with-temp-message
@defmac with-temp-message message &rest body
This construct displays a message in the echo area temporarily, during
echo area, or @code{nil} if there is none.
@end defun
-@defvar cursor-in-echo-area
-This variable controls where the cursor appears when a message is
-displayed in the echo area. If it is non-@code{nil}, then the cursor
-appears at the end of the message. Otherwise, the cursor appears at
-point---not in the echo area at all.
+@node Progress
+@subsection Reporting Operation Progress
+@cindex progress reporting
-The value is normally @code{nil}; Lisp programs bind it to @code{t}
-for brief periods of time.
-@end defvar
+ When an operation can take a while to finish, you should inform the
+user about the progress it makes. This way the user can estimate
+remaining time and clearly see that Emacs is busy working, not hung.
-@defvar echo-area-clear-hook
-This normal hook is run whenever the echo area is cleared---either by
-@code{(message nil)} or for any other reason.
-@end defvar
+ Functions listed in this section provide simple and efficient way of
+reporting operation progress. Here is a working example that does
+nothing useful:
+
+@smallexample
+(let ((progress-reporter
+ (make-progress-reporter "Collecting mana for Emacs..."
+ 0 500)))
+ (dotimes (k 500)
+ (sit-for 0.01)
+ (progress-reporter-update progress-reporter k))
+ (progress-reporter-done progress-reporter))
+@end smallexample
+
+@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
+This function creates and returns a @dfn{progress reporter}---an
+object you will use as an argument for all other functions listed
+here. The idea is to precompute as much data as possible to make
+progress reporting very fast.
+
+When this progress reporter is subsequently used, it will display
+@var{message} in the echo area, followed by progress percentage.
+@var{message} is treated as a simple string. If you need it to depend
+on a filename, for instance, use @code{format} before calling this
+function.
+
+@var{min-value} and @var{max-value} arguments stand for starting and
+final states of your operation. For instance, if you scan a buffer,
+they should be the results of @code{point-min} and @code{point-max}
+correspondingly. It is required that @var{max-value} is greater than
+@var{min-value}. If you create progress reporter when some part of
+the operation has already been completed, then specify
+@var{current-value} argument. But normally you should omit it or set
+it to @code{nil}---it will default to @var{min-value} then.
+
+Remaining arguments control the rate of echo area updates. Progress
+reporter will wait for at least @var{min-change} more percents of the
+operation to be completed before printing next message.
+@var{min-time} specifies the minimum time in seconds to pass between
+successive prints. It can be fractional. Depending on Emacs and
+system capabilities, progress reporter may or may not respect this
+last argument or do it with varying precision. Default value for
+@var{min-change} is 1 (one percent), for @var{min-time}---0.2
+(seconds.)
+
+This function calls @code{progress-reporter-update}, so the first
+message is printed immediately.
+@end defun
+
+@defun progress-reporter-update reporter value
+This function does the main work of reporting progress of your
+operation. It displays the message of @var{reporter}, followed by
+progress percentage determined by @var{value}. If percentage is zero,
+or close enough according to the @var{min-change} and @var{min-time}
+arguments, then it is omitted from the output.
-Almost all the messages displayed in the echo area are also recorded
-in the @samp{*Messages*} buffer.
+@var{reporter} must be the result of a call to
+@code{make-progress-reporter}. @var{value} specifies the current
+state of your operation and must be between @var{min-value} and
+@var{max-value} (inclusive) as passed to
+@code{make-progress-reporter}. For instance, if you scan a buffer,
+then @var{value} should be the result of a call to @code{point}.
+
+This function respects @var{min-change} and @var{min-time} as passed
+to @code{make-progress-reporter} and so does not output new messages
+on every invocation. It is thus very fast and normally you should not
+try to reduce the number of calls to it: resulting overhead will most
+likely negate your effort.
+@end defun
+
+@defun progress-reporter-force-update reporter value &optional new-message
+This function is similar to @code{progress-reporter-update} except
+that it prints a message in the echo area unconditionally.
+
+The first two arguments have the same meaning as for
+@code{progress-reporter-update}. Optional @var{new-message} allows
+you to change the message of the @var{reporter}. Since this functions
+always updates the echo area, such a change will be immediately
+presented to the user.
+@end defun
+
+@defun progress-reporter-done reporter
+This function should be called when the operation is finished. It
+prints the message of @var{reporter} followed by word ``done'' in the
+echo area.
+
+You should always call this function and not hope for
+@code{progress-reporter-update} to print ``100%.'' Firstly, it may
+never print it, there are many good reasons for this not to happen.
+Secondly, ``done'' is more explicit.
+@end defun
+
+@defmac dotimes-with-progress-reporter (var count [result]) message body...
+This is a convenience macro that works the same way as @code{dotimes}
+does, but also reports loop progress using the functions described
+above. It allows you to save some typing.
+
+You can rewrite the example in the beginning of this node using
+this macro this way:
+
+@example
+(dotimes-with-progress-reporter
+ (k 500)
+ "Collecting some mana for Emacs..."
+ (sit-for 0.01))
+@end example
+@end defmac
+
+@node Logging Messages
+@subsection Logging Messages in @samp{*Messages*}
+@cindex logging echo-area messages
+
+ Almost all the messages displayed in the echo area are also recorded
+in the @samp{*Messages*} buffer so that the user can refer back to
+them. This includes all the messages that are output with
+@code{message}.
@defopt message-log-max
This variable specifies how many lines to keep in the @samp{*Messages*}
@end example
@end defopt
+ To make @samp{*Messages*} more convenient for the user, the logging
+facility combines successive identical messages. It also combines
+successive related messages for the sake of two cases: question
+followed by answer, and a series of progress messages.
+
+ A ``question followed by an answer'' means two messages like the
+ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
+and the second is @samp{@var{question}...@var{answer}}. The first
+message conveys no additional information beyond what's in the second,
+so logging the second message discards the first from the log.
+
+ A ``series of progress messages'' means successive messages like
+those produced by @code{make-progress-reporter}. They have the form
+@samp{@var{base}...@var{how-far}}, where @var{base} is the same each
+time, while @var{how-far} varies. Logging each message in the series
+discards the previous one, provided they are consecutive.
+
+ The functions @code{make-progress-reporter} and @code{y-or-n-p}
+don't have to do anything special to activate the message log
+combination feature. It operates whenever two consecutive messages
+are logged that share a common prefix ending in @samp{...}.
+
+@node Echo Area Customization
+@subsection Echo Area Customization
+
+ These variables control details of how the echo area works.
+
+@defvar cursor-in-echo-area
+This variable controls where the cursor appears when a message is
+displayed in the echo area. If it is non-@code{nil}, then the cursor
+appears at the end of the message. Otherwise, the cursor appears at
+point---not in the echo area at all.
+
+The value is normally @code{nil}; Lisp programs bind it to @code{t}
+for brief periods of time.
+@end defvar
+
+@defvar echo-area-clear-hook
+This normal hook is run whenever the echo area is cleared---either by
+@code{(message nil)} or for any other reason.
+@end defvar
+
@defvar echo-keystrokes
This variable determines how much time should elapse before command
characters echo. Its value must be an integer or floating point number,
If the value is zero, then command input is not echoed.
@end defvar
+@defvar message-truncate-lines
+Normally, displaying a long message resizes the echo area to display
+the entire message. But if the variable @code{message-truncate-lines}
+is non-@code{nil}, the echo area does not resize, and the message is
+truncated to fit it, as in Emacs 20 and before.
+@end defvar
+
+ The variable @code{max-mini-window-height}, which specifies the
+maximum height for resizing minibuffer windows, also applies to the
+echo area (which is really a special use of the minibuffer window.
+@xref{Minibuffer Misc}.
+
@node Warnings
@section Reporting Warnings
@cindex warnings
that warning is not logged.
@end defopt
-@node Progress
-@section Reporting Operation Progress
-@cindex progress reporting
-
- When an operation can take a while to finish, you should inform the
-user about the progress it makes. This way the user can estimate
-remaining time and clearly see that Emacs is busy working, not hung.
-
- Functions listed in this section provide simple and efficient way of
-reporting operation progress. Here is a working example that does
-nothing useful:
-
-@smallexample
-(let ((progress-reporter
- (make-progress-reporter "Collecting mana for Emacs..."
- 0 500)))
- (dotimes (k 500)
- (sit-for 0.01)
- (progress-reporter-update progress-reporter k))
- (progress-reporter-done progress-reporter))
-@end smallexample
-
-@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
-This function creates and returns a @dfn{progress reporter}---an
-object you will use as an argument for all other functions listed
-here. The idea is to precompute as much data as possible to make
-progress reporting very fast.
-
-When this progress reporter is subsequently used, it will display
-@var{message} in the echo area, followed by progress percentage.
-@var{message} is treated as a simple string. If you need it to depend
-on a filename, for instance, use @code{format} before calling this
-function.
-
-@var{min-value} and @var{max-value} arguments stand for starting and
-final states of your operation. For instance, if you scan a buffer,
-they should be the results of @code{point-min} and @code{point-max}
-correspondingly. It is required that @var{max-value} is greater than
-@var{min-value}. If you create progress reporter when some part of
-the operation has already been completed, then specify
-@var{current-value} argument. But normally you should omit it or set
-it to @code{nil}---it will default to @var{min-value} then.
-
-Remaining arguments control the rate of echo area updates. Progress
-reporter will wait for at least @var{min-change} more percents of the
-operation to be completed before printing next message.
-@var{min-time} specifies the minimum time in seconds to pass between
-successive prints. It can be fractional. Depending on Emacs and
-system capabilities, progress reporter may or may not respect this
-last argument or do it with varying precision. Default value for
-@var{min-change} is 1 (one percent), for @var{min-time}---0.2
-(seconds.)
-
-This function calls @code{progress-reporter-update}, so the first
-message is printed immediately.
-@end defun
-
-@defun progress-reporter-update reporter value
-This function does the main work of reporting progress of your
-operation. It displays the message of @var{reporter}, followed by
-progress percentage determined by @var{value}. If percentage is zero,
-or close enough according to the @var{min-change} and @var{min-time}
-arguments, then it is omitted from the output.
-
-@var{reporter} must be the result of a call to
-@code{make-progress-reporter}. @var{value} specifies the current
-state of your operation and must be between @var{min-value} and
-@var{max-value} (inclusive) as passed to
-@code{make-progress-reporter}. For instance, if you scan a buffer,
-then @var{value} should be the result of a call to @code{point}.
-
-This function respects @var{min-change} and @var{min-time} as passed
-to @code{make-progress-reporter} and so does not output new messages
-on every invocation. It is thus very fast and normally you should not
-try to reduce the number of calls to it: resulting overhead will most
-likely negate your effort.
-@end defun
-
-@defun progress-reporter-force-update reporter value &optional new-message
-This function is similar to @code{progress-reporter-update} except
-that it prints a message in the echo area unconditionally.
-
-The first two arguments have the same meaning as for
-@code{progress-reporter-update}. Optional @var{new-message} allows
-you to change the message of the @var{reporter}. Since this functions
-always updates the echo area, such a change will be immediately
-presented to the user.
-@end defun
-
-@defun progress-reporter-done reporter
-This function should be called when the operation is finished. It
-prints the message of @var{reporter} followed by word ``done'' in the
-echo area.
-
-You should always call this function and not hope for
-@code{progress-reporter-update} to print ``100%.'' Firstly, it may
-never print it, there are many good reasons for this not to happen.
-Secondly, ``done'' is more explicit.
-@end defun
-
-@defmac dotimes-with-progress-reporter (var count [result]) message body...
-This is a convenience macro that works the same way as @code{dotimes}
-does, but also reports loop progress using the functions described
-above. It allows you to save some typing.
-
-You can rewrite the example in the beginning of this node using
-this macro this way:
-
-@example
-(dotimes-with-progress-reporter
- (k 500)
- "Collecting some mana for Emacs..."
- (sit-for 0.01))
-@end example
-@end defmac
-
@node Invisible Text
@section Invisible Text
current buffer.
The arguments @var{front-advance} and @var{rear-advance} specify the
-insertion type for the start of the overlay and for the end of the
-overlay, respectively. @xref{Marker Insertion Types}. If
-@var{front-advance} is non-@code{nil}, text inserted at the beginning
-of the overlay is excluded from the overlay. If @var{read-advance} is
-non-@code{nil}, text inserted at the beginning of the overlay is
-included in the overlay.
+marker insertion type for the start of the overlay and for the end of
+the overlay, respectively. @xref{Marker Insertion Types}. If they
+are both @code{nil}, the default, then the overlay extends to include
+any text inserted at the beginning, but not text inserted at the end.
+If @var{front-advance} is non-@code{nil}, text inserted at the
+beginning of the overlay is excluded from the overlay. If
+@var{rear-advance} is non-@code{nil}, text inserted at the end of the
+overlay is included in the overlay.
@end defun
@defun overlay-start overlay
length is the number of characters deleted, and the post-change
beginning and end are equal.)
+If these functions modify the buffer, they should bind
+@code{inhibit-modification-hooks} to @code{t} around doing so, to
+avoid confusing the internal mechanism that calls these hooks.
+
@item insert-in-front-hooks
@kindex insert-in-front-hooks @r{(overlay property)}
This property's value is a list of functions to be called before and
@code{(point-min)}.
@end defun
- Here's an easy way to use @code{next-overlay-change} to search for the
-next character which gets a non-@code{nil} @code{happy} property from
+ Here's a function which uses @code{next-overlay-change} to search
+for the next character which gets a given property @code{prop} from
either its overlays or its text properties (@pxref{Property Search}):
@smallexample
(defun find-overlay-prop (prop)
(save-excursion
(while (and (not (eobp))
- (not (get-char-property (point) 'happy)))
+ (not (get-char-property (point) prop)))
(goto-char (min (next-overlay-change (point))
- (next-single-property-change (point) 'happy))))
+ (next-single-property-change (point) prop))))
(point)))
@end smallexample
+ Now you can search for a @code{happy} property like this:
+
+@smallexample
+(find-overlay-prop 'happy)
+@end smallexample
+
@node Width
@section Width
@vindex default-line-spacing
You can specify the line spacing for all lines in a frame with the
-@code{line-spacing} frame parameter, @xref{Window Frame Parameters}.
+@code{line-spacing} frame parameter (@pxref{Layout Parameters}).
However, if the variable @code{default-line-spacing} is
non-@code{nil}, it overrides the frame's @code{line-spacing}
parameter. An integer value specifies the number of pixels put below
A @dfn{face} is a named collection of graphical attributes: font
family, foreground color, background color, optional underlining, and
many others. Faces are used in Emacs to control the style of display of
-particular parts of the text or the frame.
+particular parts of the text or the frame. @xref{Standard Faces,,,
+emacs, The GNU Emacs Manual}, for the list of faces Emacs normally
+comes with.
@cindex face id
Each face has its own @dfn{face number}, which distinguishes faces at
face name a special meaning in one frame if you wish.
@menu
-* Standard Faces:: The faces Emacs normally comes with.
* Defining Faces:: How to define a face with @code{defface}.
* Face Attributes:: What is in a face?
* Attribute Functions:: Functions to examine and set face attributes.
that handle a range of character sets.
@end menu
-@node Standard Faces
-@subsection Standard Faces
-
- This table lists all the standard faces and their uses. Most of them
-are used for displaying certain parts of the frames or certain kinds of
-text; you can control how those places look by customizing these faces.
-
-@table @code
-@item default
-@kindex default @r{(face name)}
-This face is used for ordinary text.
-
-@item mode-line
-@kindex mode-line @r{(face name)}
-This face is used for the mode line of the selected window, and for
-menu bars when toolkit menus are not used---but only if
-@code{mode-line-inverse-video} is non-@code{nil}.
-
-@item modeline
-@kindex modeline @r{(face name)}
-This is an alias for the @code{mode-line} face, for compatibility with
-old Emacs versions.
-
-@item mode-line-inactive
-@kindex mode-line-inactive @r{(face name)}
-This face is used for mode lines of non-selected windows.
-This face inherits from @code{mode-line}, so changes
-in that face affect all windows.
-
-@item header-line
-@kindex header-line @r{(face name)}
-This face is used for the header lines of windows that have them.
-
-@item menu
-This face controls the display of menus, both their colors and their
-font. (This works only on certain systems.)
-
-@item fringe
-@kindex fringe @r{(face name)}
-This face controls the default colors of window fringes, the thin
-areas on either side that are used to display continuation and
-truncation glyphs. Other faces used to display bitmaps in the fringe
-are implicitly merged with this face.
-
-@item minibuffer-prompt
-@kindex minibuffer-prompt @r{(face name)}
-@vindex minibuffer-prompt-properties
-This face is used for the text of minibuffer prompts. By default,
-Emacs automatically adds this face to the value of
-@code{minibuffer-prompt-properties}, which is a list of text
-properties used to display the prompt text.
-
-@item scroll-bar
-@kindex scroll-bar @r{(face name)}
-This face controls the colors for display of scroll bars.
-
-@item tool-bar
-@kindex tool-bar @r{(face name)}
-This face is used for display of the tool bar, if any.
-
-@item region
-@kindex region @r{(face name)}
-This face is used for highlighting the region in Transient Mark mode.
-
-@item secondary-selection
-@kindex secondary-selection @r{(face name)}
-This face is used to show any secondary selection you have made.
-
-@item highlight
-@kindex highlight @r{(face name)}
-This face is meant to be used for highlighting for various purposes.
-
-@item mode-line-highlight
-@kindex mode-line-highlight @r{(face name)}
-This face is used for highlighting something on @code{mode-line} or
-@code{header-line} for various purposes.
-
-@item trailing-whitespace
-@kindex trailing-whitespace @r{(face name)}
-This face is used to display excess whitespace at the end of a line,
-if @code{show-trailing-whitespace} is non-@code{nil}.
-
-@item escape-glyph
-@kindex escape-glyph @r{(face name)}
-This face is used to display control characters and escape glyphs.
-@end table
-
- In contrast, these faces are provided to change the appearance of text
-in specific ways. You can use them on specific text, when you want
-the effects they produce.
-
-@table @code
-@item bold
-@kindex bold @r{(face name)}
-This face uses a bold font, if possible. It uses the bold variant of
-the frame's font, if it has one. It's up to you to choose a default
-font that has a bold variant, if you want to use one.
-
-@item italic
-@kindex italic @r{(face name)}
-This face uses the italic variant of the frame's font, if it has one.
-
-@item bold-italic
-@kindex bold-italic @r{(face name)}
-This face uses the bold italic variant of the frame's font, if it has
-one.
-
-@item underline
-@kindex underline @r{(face name)}
-This face underlines text.
-
-@item fixed-pitch
-@kindex fixed-pitch @r{(face name)}
-This face forces use of a particular fixed-width font.
-
-@item variable-pitch
-@kindex variable-pitch @r{(face name)}
-This face forces use of a particular variable-width font. It's
-reasonable to customize this to use a different variable-width font, if
-you like, but you should not make it a fixed-width font.
-
-@item shadow
-@kindex shadow @r{(face name)}
-This face is used for making the text less noticeable than the
-surrounding ordinary text.
-@end table
-
-@defvar show-trailing-whitespace
-@tindex show-trailing-whitespace
-If this variable is non-@code{nil}, Emacs uses the
-@code{trailing-whitespace} face to display any spaces and tabs at the
-end of a line.
-@end defvar
-
@node Defining Faces
@subsection Defining Faces
Non-@code{nil} means do underline; @code{nil} means don't.
@end defun
+@defun set-face-inverse-video-p face inverse-video-p &optional frame
+This function sets the @code{:inverse-video} attribute of face
+@var{face}.
+@end defun
+
@defun invert-face face &optional frame
-This function inverts the @code{:inverse-video} attribute of face
-@var{face}. If the attribute is @code{nil}, this function sets it to
-@code{t}, and vice versa.
+This function swaps the foreground and background colors of face
+@var{face}.
@end defun
These functions examine the attributes of a face. If you don't
value for that attribute.
@defun face-foreground face &optional frame inherit
-@defunx face-background face &optional frame
+@defunx face-background face &optional frame inherit
These functions return the foreground color (or background color,
respectively) of face @var{face}, as a string.
@item
With a region that is active. In Transient Mark mode, the region is
-highlighted with the face @code{region} (@pxref{Standard Faces}).
+highlighted with the face @code{region} (@pxref{Standard Faces,,,
+emacs, The GNU Emacs Manual}).
@item
With special glyphs. Each glyph can specify a particular face
whether the windows in the frame have vertical scroll bars, and
whether they are on the left or right. The frame parameter
@code{scroll-bar-width} specifies how wide they are (@code{nil}
-meaning the default). @xref{Window Frame Parameters}.
+meaning the default). @xref{Layout Parameters}.
@defun frame-current-scroll-bars &optional frame
This function reports the scroll bar type settings for frame
@end smallexample
@end deffn
-@node Inverse Video
-@section Inverse Video
-@cindex Inverse Video
-
-@defopt inverse-video
-@cindex highlighting
-This variable controls whether Emacs uses inverse video for all text
-on the screen. Non-@code{nil} means yes, @code{nil} means no. The
-default is @code{nil}.
-@end defopt
-
-@defopt mode-line-inverse-video
-This variable controls the use of inverse video for mode lines and
-menu bars. If it is non-@code{nil}, then these lines are displayed in
-the face @code{mode-line}. Otherwise, these lines are displayed
-normally, just like other text. The default is @code{t}.
-@end defopt
-
@node Usual Display
@section Usual Display Conventions