[PATCH 4/9] gdb/doc: Restructure frame command documentation.

[Andrew Burgess <andrew dot burgess at embecosm dot com>]

The 'frame' command is documented in two places.  The 'select-frame'
command is only mentioned in one of these places.

Of the two places, having the description of 'frame' and 'select-frame'
in the section 'Selecting a Frame' seems like the most obvious choice,
which is where things like 'up' and 'down' are also documented.

This commit moves the documentation of 'frame' and 'select-frame' into
the 'Selecting a Frame' section, and removes the duplicate documentation
of the 'frame' command.

At the same time I have reordered the sections in the 'Examining the
Stack' chapter, moving the discussion of frame filters to the end of the
chapter; it feels odd that we talk about frame filters before such basic
things like navigating the stack, or examining stack frames in general.

gdb/doc/ChangeLog:

	* gdb.texinfo (Frames): Remove 'frame' and 'select-frame'
	description.
	(Frame Filter Management): Move to later in the 'Examining the
	Stack' chapter.
	(Selection): Add entry for 'select-frame'.
---
 gdb/doc/ChangeLog   |   8 ++
 gdb/doc/gdb.texinfo | 309 +++++++++++++++++++++++++---------------------------
 2 files changed, 157 insertions(+), 160 deletions(-)

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 29c66b8..f7d7a94 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,11 @@
+2015-09-11  Andrew Burgess  <andrew.burgess@embecosm.com>
+
+	* gdb.texinfo (Frames): Remove 'frame' and 'select-frame'
+	description.
+	(Frame Filter Management): Move to later in the 'Examining the
+	Stack' chapter.
+	(Selection): Add entry for 'select-frame'.
+
 2015-08-24  Pedro Alves  <palves@redhat.com>
 
 	* gdb.texinfo (Remote Configuration): Document the "set/show
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index cd0abad..225e57d 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6948,23 +6948,6 @@ it had a separate frame, which is numbered zero as usual, allowing
 correct tracing of the function call chain.  However, @value{GDBN} has
 no provision for frameless functions elsewhere in the stack.
 
-@table @code
-@kindex frame@r{, command}
-@cindex current stack frame
-@item frame @r{[}@var{framespec}@r{]}
-The @code{frame} command allows you to move from one stack frame to another,
-and to print the stack frame you select.  The @var{framespec} may be either the
-address of the frame or the stack frame number.  Without an argument,
-@code{frame} prints the current stack frame.
-
-@kindex select-frame
-@cindex selecting frame silently
-@item select-frame
-The @code{select-frame} command allows you to move from one stack frame
-to another without printing the frame.  This is the silent version of
-@code{frame}.
-@end table
-
 @node Backtrace
 @section Backtraces
 
@@ -7164,149 +7147,6 @@ Display an absolute filename.
 Show the current way to display filenames.
 @end table
 
-@node Frame Filter Management
-@section Management of Frame Filters.
-@cindex managing frame filters
-
-Frame filters are Python based utilities to manage and decorate the
-output of frames.  @xref{Frame Filter API}, for further information.
-
-Managing frame filters is performed by several commands available
-within @value{GDBN}, detailed here.
-
-@table @code
-@kindex info frame-filter
-@item info frame-filter
-Print a list of installed frame filters from all dictionaries, showing
-their name, priority and enabled status.
-
-@kindex disable frame-filter
-@anchor{disable frame-filter all}
-@item disable frame-filter @var{filter-dictionary} @var{filter-name}
-Disable a frame filter in the dictionary matching
-@var{filter-dictionary} and @var{filter-name}.  The
-@var{filter-dictionary} may be @code{all}, @code{global},
-@code{progspace}, or the name of the object file where the frame filter
-dictionary resides.  When @code{all} is specified, all frame filters
-across all dictionaries are disabled.  The @var{filter-name} is the name
-of the frame filter and is used when @code{all} is not the option for
-@var{filter-dictionary}.  A disabled frame-filter is not deleted, it
-may be enabled again later.
-
-@kindex enable frame-filter
-@item enable frame-filter @var{filter-dictionary} @var{filter-name}
-Enable a frame filter in the dictionary matching
-@var{filter-dictionary} and @var{filter-name}.  The
-@var{filter-dictionary} may be @code{all}, @code{global},
-@code{progspace} or the name of the object file where the frame filter
-dictionary resides.  When @code{all} is specified, all frame filters across
-all dictionaries are enabled.  The @var{filter-name} is the name of the frame
-filter and is used when @code{all} is not the option for
-@var{filter-dictionary}.
-
-Example:
-
-@smallexample
-(gdb) info frame-filter
-
-global frame-filters:
-  Priority  Enabled  Name
-  1000      No       PrimaryFunctionFilter
-  100       Yes      Reverse
-
-progspace /build/test frame-filters:
-  Priority  Enabled  Name
-  100       Yes      ProgspaceFilter
-
-objfile /build/test frame-filters:
-  Priority  Enabled  Name
-  999       Yes      BuildProgra Filter
-
-(gdb) disable frame-filter /build/test BuildProgramFilter
-(gdb) info frame-filter
-
-global frame-filters:
-  Priority  Enabled  Name
-  1000      No       PrimaryFunctionFilter
-  100       Yes      Reverse
-
-progspace /build/test frame-filters:
-  Priority  Enabled  Name
-  100       Yes      ProgspaceFilter
-
-objfile /build/test frame-filters:
-  Priority  Enabled  Name
-  999       No       BuildProgramFilter
-
-(gdb) enable frame-filter global PrimaryFunctionFilter
-(gdb) info frame-filter
-
-global frame-filters:
-  Priority  Enabled  Name
-  1000      Yes      PrimaryFunctionFilter
-  100       Yes      Reverse
-
-progspace /build/test frame-filters:
-  Priority  Enabled  Name
-  100       Yes      ProgspaceFilter
-
-objfile /build/test frame-filters:
-  Priority  Enabled  Name
-  999       No       BuildProgramFilter
-@end smallexample
-
-@kindex set frame-filter priority
-@item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority}
-Set the @var{priority} of a frame filter in the dictionary matching
-@var{filter-dictionary}, and the frame filter name matching
-@var{filter-name}.  The @var{filter-dictionary} may be @code{global},
-@code{progspace} or the name of the object file where the frame filter
-dictionary resides.  The @var{priority} is an integer.
-
-@kindex show frame-filter priority
-@item show frame-filter priority @var{filter-dictionary} @var{filter-name}
-Show the @var{priority} of a frame filter in the dictionary matching
-@var{filter-dictionary}, and the frame filter name matching
-@var{filter-name}.  The @var{filter-dictionary} may be @code{global},
-@code{progspace} or the name of the object file where the frame filter
-dictionary resides.
-
-Example:
-
-@smallexample
-(gdb) info frame-filter
-
-global frame-filters:
-  Priority  Enabled  Name
-  1000      Yes      PrimaryFunctionFilter
-  100       Yes      Reverse
-
-progspace /build/test frame-filters:
-  Priority  Enabled  Name
-  100       Yes      ProgspaceFilter
-
-objfile /build/test frame-filters:
-  Priority  Enabled  Name
-  999       No       BuildProgramFilter
-
-(gdb) set frame-filter priority global Reverse 50
-(gdb) info frame-filter
-
-global frame-filters:
-  Priority  Enabled  Name
-  1000      Yes      PrimaryFunctionFilter
-  50        Yes      Reverse
-
-progspace /build/test frame-filters:
-  Priority  Enabled  Name
-  100       Yes      ProgspaceFilter
-
-objfile /build/test frame-filters:
-  Priority  Enabled  Name
-  999       No       BuildProgramFilter
-@end smallexample
-@end table
-
 @node Selection
 @section Selecting a Frame
 
@@ -7374,6 +7214,13 @@ editing program by typing @code{edit}.
 for details.
 
 @table @code
+@kindex select-frame
+@item select-frame
+The @code{select-frame} command is a variant of @code{frame} that does
+not display the new frame after selecting it.  This command is
+intended primarily for use in @value{GDBN} command scripts, where the
+output might be unnecessary and distracting.
+
 @kindex down-silently
 @kindex up-silently
 @item up-silently @var{n}
@@ -7450,6 +7297,148 @@ accessible at the point of execution of the selected frame.
 
 @end table
 
+@node Frame Filter Management
+@section Management of Frame Filters.
+@cindex managing frame filters
+
+Frame filters are Python based utilities to manage and decorate the
+output of frames.  @xref{Frame Filter API}, for further information.
+
+Managing frame filters is performed by several commands available
+within @value{GDBN}, detailed here.
+
+@table @code
+@kindex info frame-filter
+@item info frame-filter
+Print a list of installed frame filters from all dictionaries, showing
+their name, priority and enabled status.
+
+@kindex disable frame-filter
+@anchor{disable frame-filter all}
+@item disable frame-filter @var{filter-dictionary} @var{filter-name}
+Disable a frame filter in the dictionary matching
+@var{filter-dictionary} and @var{filter-name}.  The
+@var{filter-dictionary} may be @code{all}, @code{global},
+@code{progspace}, or the name of the object file where the frame filter
+dictionary resides.  When @code{all} is specified, all frame filters
+across all dictionaries are disabled.  The @var{filter-name} is the name
+of the frame filter and is used when @code{all} is not the option for
+@var{filter-dictionary}.  A disabled frame-filter is not deleted, it
+may be enabled again later.
+
+@kindex enable frame-filter
+@item enable frame-filter @var{filter-dictionary} @var{filter-name}
+Enable a frame filter in the dictionary matching
+@var{filter-dictionary} and @var{filter-name}.  The
+@var{filter-dictionary} may be @code{all}, @code{global},
+@code{progspace} or the name of the object file where the frame filter
+dictionary resides.  When @code{all} is specified, all frame filters across
+all dictionaries are enabled.  The @var{filter-name} is the name of the frame
+filter and is used when @code{all} is not the option for
+@var{filter-dictionary}.
+
+Example:
+
+@smallexample
+(gdb) info frame-filter
+
+global frame-filters:
+  Priority  Enabled  Name
+  1000      No       PrimaryFunctionFilter
+  100       Yes      Reverse
+
+progspace /build/test frame-filters:
+  Priority  Enabled  Name
+  100       Yes      ProgspaceFilter
+
+objfile /build/test frame-filters:
+  Priority  Enabled  Name
+  999       Yes      BuildProgra Filter
+
+(gdb) disable frame-filter /build/test BuildProgramFilter
+(gdb) info frame-filter
+
+global frame-filters:
+  Priority  Enabled  Name
+  1000      No       PrimaryFunctionFilter
+  100       Yes      Reverse
+
+progspace /build/test frame-filters:
+  Priority  Enabled  Name
+  100       Yes      ProgspaceFilter
+
+objfile /build/test frame-filters:
+  Priority  Enabled  Name
+  999       No       BuildProgramFilter
+
+(gdb) enable frame-filter global PrimaryFunctionFilter
+(gdb) info frame-filter
+
+global frame-filters:
+  Priority  Enabled  Name
+  1000      Yes      PrimaryFunctionFilter
+  100       Yes      Reverse
+
+progspace /build/test frame-filters:
+  Priority  Enabled  Name
+  100       Yes      ProgspaceFilter
+
+objfile /build/test frame-filters:
+  Priority  Enabled  Name
+  999       No       BuildProgramFilter
+@end smallexample
+
+@kindex set frame-filter priority
+@item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority}
+Set the @var{priority} of a frame filter in the dictionary matching
+@var{filter-dictionary}, and the frame filter name matching
+@var{filter-name}.  The @var{filter-dictionary} may be @code{global},
+@code{progspace} or the name of the object file where the frame filter
+dictionary resides.  The @var{priority} is an integer.
+
+@kindex show frame-filter priority
+@item show frame-filter priority @var{filter-dictionary} @var{filter-name}
+Show the @var{priority} of a frame filter in the dictionary matching
+@var{filter-dictionary}, and the frame filter name matching
+@var{filter-name}.  The @var{filter-dictionary} may be @code{global},
+@code{progspace} or the name of the object file where the frame filter
+dictionary resides.
+
+Example:
+
+@smallexample
+(gdb) info frame-filter
+
+global frame-filters:
+  Priority  Enabled  Name
+  1000      Yes      PrimaryFunctionFilter
+  100       Yes      Reverse
+
+progspace /build/test frame-filters:
+  Priority  Enabled  Name
+  100       Yes      ProgspaceFilter
+
+objfile /build/test frame-filters:
+  Priority  Enabled  Name
+  999       No       BuildProgramFilter
+
+(gdb) set frame-filter priority global Reverse 50
+(gdb) info frame-filter
+
+global frame-filters:
+  Priority  Enabled  Name
+  1000      Yes      PrimaryFunctionFilter
+  50        Yes      Reverse
+
+progspace /build/test frame-filters:
+  Priority  Enabled  Name
+  100       Yes      ProgspaceFilter
+
+objfile /build/test frame-filters:
+  Priority  Enabled  Name
+  999       No       BuildProgramFilter
+@end smallexample
+@end table
 
 @node Source
 @chapter Examining Source Files
-- 
2.5.1