--- a/man/lispref/gutter.texi	Mon Apr 19 06:40:45 2004 +0000
+++ b/man/lispref/gutter.texi	Mon Apr 19 08:02:38 2004 +0000
@@ -14,15 +14,13 @@
 
 @menu
 * Gutter Intro::		An introduction.
-* Creating Gutter::             How to create a gutter.
-* Gutter Descriptor Format::	Accessing and modifying a gutter's
-                                  properties.
+* Creating Gutters::            How to create a gutter.
 * Specifying a Gutter::		Setting a gutter's contents.
 * Other Gutter Variables::	Controlling the size of gutters.
 * Common Gutter Widgets::       Things to put in gutters.
 @end menu
 
-@node Gutter Intro, Creating Gutter, Gutter, Gutter
+@node Gutter Intro, Creating Gutters, Gutter, Gutter
 @section Gutter Intro
 
   A @dfn{gutter} is a rectangle displayed along one edge of a frame.  It
@@ -37,7 +35,7 @@
 be per-buffer, per-frame, etc., using specifiers (@pxref{Specifiers}).
 
   Normally, there is one gutter displayed in a frame.  Usually, this is
-the default gutter, containing buffer tabs, but modes cab override this
+the default gutter, containing buffer tabs, but modes can override this
 and substitute their own gutter.  This default gutter is usually
 positioned along the top of the frame, but this can be changed using
 @code{set-default-gutter-position}.
@@ -59,8 +57,8 @@
 the user sets the default gutter to the same position, it will just
 not be visible.
 
-@node Creating Gutter, Gutter Descriptor Format, Gutter Intro, Gutter
-@section Creating Gutter
+@node Creating Gutters, Specifying a Gutter, Gutter Intro, Gutter
+@section Creating Gutters
 
 @defun make-gutter-specifier spec-list
 
@@ -75,9 +73,15 @@
 @code{left-gutter}, @code{right-gutter}, and @code{bottom-gutter} are
 always gutter specifiers.
 
-Valid gutter instantiators are called "gutter descriptors" and are
-either strings or property-lists of strings.  See @code{default-gutter}
-for a description of the exact format.
+Valid gutter instantiators are called ``gutter descriptors.''  A gutter
+descriptor may be a string, a property-list with symbol keys and string
+values, or @code{nil}.  If @code{nil}, nothing will be displayed in the
+gutter.  If a string, the string will be displayed, with text properties
+such as faces and additional glyphs taken from the extents in the
+string, if any.  If a property-list of strings, the string values will
+be conditionally concatenated according to the contents of the
+corresponding @samp{gutter-visible} variable, and displayed according to
+any text properties they contain.
 @end defun
 
 @defun make-gutter-size-specifier spec-list
@@ -88,16 +92,19 @@
 or a list of instantiators.  @xref{Specifiers}, for more information
 about specifiers.
 
-Gutter-size specifiers are used to specify the size of a gutter.  The
-values of the variables @code{default-gutter-size},
-@code{top-gutter-size}, @code{left-gutter-size},
-@code{right-gutter-size}, and @code{bottom-gutter-size} are always
-gutter-size specifiers.
+Gutter-size specifiers are used to specify the size of a gutter.
+The width of top and bottom gutters and the height of left and right
+gutters are always adjusted to the size of the frame, so ``size'' means
+``thickness,'' @emph{i.e.}, height for top and bottom gutters and width
+for left and right gutters.  The values of the variables
+@code{default-gutter-size}, @code{top-gutter-size},
+@code{left-gutter-size}, @code{right-gutter-size}, and
+@code{bottom-gutter-size} are always gutter-size specifiers.
 
 Valid gutter-size instantiators are either integers or the special
-symbol @code{autodetect}. If a gutter-size is set to @code{autodetect}
+symbol @code{autodetect}.  If a gutter-size is set to @code{autodetect}
 them the size of the gutter will be adjusted to just accommodate the
-gutters contents. @code{autodetect} only works for top and bottom
+gutter's contents.  @code{autodetect} only works for top and bottom
 gutters.
 @end defun
 
@@ -117,125 +124,12 @@
 
 Valid gutter-visible instantiators are @code{t}, @code{nil} or a list of
 symbols.  If a gutter-visible instantiator is set to a list of symbols,
-and the corresponding gutter specification is a property-list strings,
-then elements of the gutter specification will only be visible if the
-corresponding symbol occurs in the gutter-visible instantiator.
+and the corresponding gutter specification is a property-list of strings,
+then property values of the gutter specification will only be visible if the
+corresponding key occurs in the gutter-visible instantiator.
 @end defun
 
-@node Gutter Descriptor Format, Specifying a Gutter, Creating Gutter, Gutter
-@section Gutter Descriptor Format
-
-  The contents of a gutter are specified using a @dfn{gutter descriptor}.
-The format of a gutter descriptor is a list of @dfn{gutter button
-descriptors}.  Each gutter button descriptor is a vector in one of the
-following formats:
-
-@itemize @bullet
-@item
-@code{[@var{glyph-list} @var{function} @var{enabled-p} @var{help}]}
-@item
-@code{[:style @var{2d-or-3d}]}
-@item
-@code{[:style @var{2d-or-3d} :size @var{width-or-height}]}
-@item
-@code{[:size @var{width-or-height} :style @var{2d-or-3d}]}
-@end itemize
-
-  Optionally, one of the gutter button descriptors may be @code{nil}
-instead of a vector; this signifies the division between the gutter
-buttons that are to be displayed flush-left, and the buttons to be
-displayed flush-right.
-
-  The first vector format above specifies a normal gutter button;
-the others specify blank areas in the gutter.
-
-  For the first vector format:
-
-@itemize @bullet
-@item
-@var{glyph-list} should be a list of one to six glyphs (as created by
-@code{make-glyph}) or a symbol whose value is such a list.  The first
-glyph, which must be provided, is the glyph used to display the gutter
-button when it is in the ``up'' (not pressed) state.  The optional
-second glyph is for displaying the button when it is in the ``down''
-(pressed) state.  The optional third glyph is for when the button is
-disabled.  The last three glyphs are for displaying the button in the
-``up'', ``down'', and ``disabled'' states, respectively, but are used
-when the user has called for captioned gutter buttons (using
-@code{gutter-buttons-captioned-p}).  The function
-@code{gutter-make-button-list} is useful in creating these glyph lists.
-
-@item
-Even if you do not provide separate down-state and disabled-state
-glyphs, the user will still get visual feedback to indicate which
-state the button is in.  Buttons in the up-state are displayed
-with a shadowed border that gives a raised appearance to the
-button.  Buttons in the down-state are displayed with shadows that
-give a recessed appearance.  Buttons in the disabled state are
-displayed with no shadows, giving a 2-d effect.
-
-@item
-If some of the gutter glyphs are not provided, they inherit as follows:
-
-@example
-     UP:                up
-     DOWN:              down -> up
-     DISABLED:          disabled -> up
-     CAP-UP:            cap-up -> up
-     CAP-DOWN:          cap-down -> cap-up -> down -> up
-     CAP-DISABLED:      cap-disabled -> cap-up -> disabled -> up
-@end example
-
-@item
-The second element @var{function} is a function to be called when the
-gutter button is activated (i.e. when the mouse is released over the
-gutter button, if the press occurred in the gutter).  It can be any
-form accepted by @code{call-interactively}, since this is how it is
-invoked.
-
-@item
-The third element @var{enabled-p} specifies whether the gutter button
-is enabled (disabled buttons do nothing when they are activated, and are
-displayed differently; see above).  It should be either a boolean or a
-form that evaluates to a boolean.
-
-@item
-The fourth element @var{help}, if non-@code{nil}, should be a string.
-This string is displayed in the echo area when the mouse passes over the
-gutter button.
-@end itemize
-
-  For the other vector formats (specifying blank areas of the gutter):
-
-@itemize @bullet
-@item
-@var{2d-or-3d} should be one of the symbols @code{2d} or @code{3d},
-indicating whether the area is displayed with shadows (giving it a
-raised, 3-d appearance) or without shadows (giving it a flat
-appearance).
-
-@item
-@var{width-or-height} specifies the length, in pixels, of the blank
-area.  If omitted, it defaults to a device-specific value (8 pixels for
-X devices).
-@end itemize
-
-@defun gutter-make-button-list up &optional down disabled cap-up cap-down cap-disabled
-This function calls @code{make-glyph} on each arg and returns a list of
-the results.  This is useful for setting the first argument of a gutter
-button descriptor (typically, the result of this function is assigned
-to a symbol, which is specified as the first argument of the gutter
-button descriptor).
-@end defun
-
-@defun check-gutter-button-syntax button &optional noerror
-Verify the syntax of entry @var{button} in a gutter description list.
-If you want to verify the syntax of a gutter description list as a
-whole, use @code{check-valid-instantiator} with a specifier type of
-@code{gutter}.
-@end defun
-
-@node Specifying a Gutter, Other Gutter Variables, Gutter Descriptor Format, Gutter
+@node Specifying a Gutter, Other Gutter Variables, Creating Gutters, Gutter
 @section Specifying a Gutter
 
   In order to specify the contents of a gutter, set one of the specifier
@@ -315,7 +209,7 @@
 This function returns non-@code{nil} if @var{object} is a gutter specifier.
 Gutter specifiers are the actual objects contained in the gutter
 variables described above, and their valid instantiators are
-gutter descriptors (@pxref{Gutter Descriptor Format}).
+gutter descriptors.
 @end defun
 
 @node Other Gutter Variables, Common Gutter Widgets, Specifying a Gutter, Gutter
@@ -397,6 +291,7 @@
 @code{default-gutter-visible-p} and all of the position-specific
 gutter visibility specifiers have a fallback value of true.
 
+@c #### is this true?
   Internally, gutter thickness and visibility specifiers are instantiated
 in both window and frame domains, for different purposes.  The value in
 the domain of a frame's selected window specifies the actual gutter
@@ -415,18 +310,6 @@
 selected window specifies that the left gutter is not visible, so it is
 expanded to take up the slack.
 
-@defvr Specifier gutter-buttons-captioned-p
-Whether gutter buttons are captioned.  This affects which glyphs from a
-gutter button descriptor are chosen.  @xref{Gutter Descriptor Format}.
-@end defvr
-
-  You can also reset the gutter to what it was when XEmacs started up.
-
-@defvr Constant initial-gutter-spec
-The gutter descriptor used to initialize @code{default-gutter} at
-startup.
-@end defvr
-
 @node Common Gutter Widgets, , Other Gutter Variables, Gutter
 @section Common Gutter Widgets
 
@@ -439,20 +322,26 @@
   A more common use for the gutter is to hold some kind of active
 widget.  The buffer-tab facility, available in all XEmacs frames,
 creates an array of file-folder-like tabs, which the user can click with
-the mouse to switch buffers.  W3 uses a progress-bar widget in the
+the mouse to switch buffers.  W3 and font-lock use progress-bar widgets in the
 bottom gutter to give a visual indication of the progress of
-time-consuming operations like downloading.
+time-consuming operations like downloading and syntax highlighting.
+
+@c #### Remove the following sentence when the subnodes are created.
+These widgets are currently documented only in the library
+@file{gutter-items}.
 
 @menu
 * Buffer Tabs::         Tabbed divider index metaphor for switching buffers.
 * Progress Bars::       Visual indication of operation progress.
 @end menu
 
+
 @node Buffer Tabs, Progress Bars, ,Common Gutter Widgets
 @subsection Buffer Tabs
 
   Not documented yet.
 
+
 @node Progress Bars,  , Buffer Tabs, Common Gutter Widgets
 @subsection Progress Bars