changeset 65955:982867e0921a

(Speedbar): Clarify the text.

--- a/man/frames.texi	Sun Oct 09 20:56:54 2005 +0000
+++ b/man/frames.texi	Sun Oct 09 21:19:40 2005 +0000
@@ -545,47 +545,56 @@
 the variable should be @code{nil}.
 
 @node Speedbar
-@section Making and Using a Speedbar Frame
+@section Speedbar Frames
 @cindex speedbar
 
-  The @dfn{Speedbar} is a special frame that is used to summarize
-information related to other buffers.  Normally, it displays a menu of
-files you could visit and tags within those files.  Type @kbd{M-x
-speedbar} to enable the speedbar and associate it with the current
-frame (which is called the speedbar's @dfn{attached frame}).
+@cindex attached frame (of speedbar)
+  The @dfn{speedbar} is a special frame for conveniently navigating in
+or operating on another frame.  The speedbar, when it exists, is
+always associated with a specific frame, called its @dfn{attached
+frame}; all speedbar operations act on that frame.
 
-  Currently, only one speedbar is supported at a time.  To dismiss the
-speedbar, select it and type @kbd{q} or @kbd{M-x speedbar}, or delete
-the frame or window normally.  You can then attach the speedbar to a
-different frame by calling @kbd{M-x speedbar} from that frame.
+  Type @kbd{M-x speedbar} to create the speedbar and associate it with
+the current frame.  To dismiss the speedbar, select it and type
+@kbd{q} or @kbd{M-x speedbar}.  (You can also delete the speedbar
+frame like any other Emacs frame.)  You can then attach the speedbar
+to a different frame by typing @kbd{M-x speedbar} in that frame.
+@c ??? If the speedbar is active, and I type M-x speedbar in another
+@c frame, does that attach the speedbar to that other frame?
+@c If not, it should!  -- rms
 
-  When you initially launch the speedbar, it starts in @dfn{File
-Display Mode}, showing the current directory of the selected window of
-the attached frame, one file per line.  Clicking on a file name visits
-that file in the attached frame, and clicking on a directory name
-shows that directory in the speedbar (@pxref{Mouse References}).  Each
-line also has a box, @samp{[+]} or @samp{<+>}, that you can click on
-to @dfn{expand} the contents of that item.  Expanding a directory adds
-the contents of that directory to the speedbar display, underneath the
-directory's own line.  Expanding an ordinary file adds a list of the
-tags in that file to the speedbar display; you can click on a tag name
-to jump to that tag in the attached frame.  When a file or directory
-is expanded, the @samp{[+]} changes to @samp{[-]}; you can click on
-that box to @dfn{contract} the item, hiding its contents.
+@c ??? When you visit a file in this way, does it appear
+in the selected window?  In a new window in the same frame? -- rms
+  The speedbar can operate in various modes.  Its default mode is
+@dfn{File Display} mode, which shows the files in the current
+directory of the selected window of the attached frame, one file per
+line.  Clicking on a file name visits that file in the attached frame,
+and clicking on a directory name shows that directory in the speedbar
+(@pxref{Mouse References}).  Each line also has a box, @samp{[+]} or
+@samp{<+>}, that you can click on to @dfn{expand} the contents of that
+item.  Expanding a directory adds the contents of that directory to
+the speedbar display, underneath the directory's own line.  Expanding
+an ordinary file adds a list of the tags in that file to the speedbar
+display; you can click on a tag name to jump to that tag in the
+attached frame.  When a file or directory is expanded, the @samp{[+]}
+changes to @samp{[-]}; you can click on that box to @dfn{contract} the
+item, hiding its contents.
 
-  You can also use the keyboard to navigate the speedbar.  Typing
-@kbd{RET} is equivalent to clicking the item on the current line, and
-@kbd{SPC} expands or contracts the item.  @kbd{U} displays the parent
-directory of the current directory.  To copy, delete, or rename the
-file on the current line, type @kbd{C}, @kbd{D}, and @kbd{R}
-respectively.  To create a new directory, type @kbd{M}.
+  You navigate through the speedbar using the keyboard, too.  Typing
+@kbd{RET} while point is on a line in the speedbar is equivalent to
+clicking the item on the current line, and @kbd{SPC} expands or
+contracts the item.  @kbd{U} displays the parent directory of the
+current directory.  To copy, delete, or rename the file on the current
+line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively.  To create a
+new directory, type @kbd{M}.
 
-  The speedbar is not limited to showing files.  Type @kbd{b} to enter
-@dfn{Buffer Display Mode}, in which the speedbar displays a list of
-Emacs buffers.  To return to File Display Mode, type @kbd{f}.  You can
-also change the display mode by clicking @kbd{mouse-3} anywhere in the
-speedbar window (or @kbd{mouse-1} on the mode-line) and selecting
-@samp{Displays} in the pop-up menu.
+  Another general-purpose speedbar mode is @dfn{Buffer Display} mode;
+in this mode, the speedbar displays a list of Emacs buffers.  To
+switch to this mode, type @kbd{b} in the speedbar.  To return to File
+Display mode, type @kbd{f}.  You can also change the display mode by
+clicking @kbd{mouse-3} anywhere in the speedbar window (or
+@kbd{mouse-1} on the mode-line) and selecting @samp{Displays} in the
+pop-up menu.
 
   Some major modes, including Rmail mode, Info, and GUD, have
 specialized ways of putting useful items into the speedbar for you to