[PATCH] gdb: Rewrite documentation for layout and focus commands.

[PATCH] gdb: Rewrite documentation for layout and focus commands.

[Andrew Burgess]

The following patch changes the documentation for the layout and focus
commands.  Though I have extended the documentation for layout
slightly most of this patch is really about reformatting the layout of
the documentation.

The change is really just my personal preference, but I think the new
layout is clearer, do people agree?

Thanks,
Andrew

---

Changes the documentation for the layout and focus commands.

Instead of documenting each layout (or focus) sub-command as a separate
command, document a single layout (and focus) command which takes a
parameter, then list the possible parameters in a table nested under
each command.

The documentation for the layout command has been extended little to
make it clearer which windows are shown in each layout.

gdb/ChangeLog:

	* doc/gdb.texinfo (TUI): Restructure documentation on TUI layout
	and focus commands.
---
 gdb/ChangeLog       |  5 +++++
 gdb/doc/gdb.texinfo | 49 +++++++++++++++++++++++++++++++++----------------
 2 files changed, 38 insertions(+), 16 deletions(-)

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 201af51..bbc0291 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,8 @@
+2015-07-06  Andrew Burgess  <andrew.burgess@embecosm.com>
+
+	* doc/gdb.texinfo (TUI): Restructure documentation on TUI layout
+	and focus commands.
+
 2015-07-02  Kevin Buettner  <kevinb@redhat.com>
 
 	* rx-tdep.c (RX_USP_REGNUM, RX_BPC_REGNUM): New constants.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 812917b..509e1db 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -25070,43 +25070,60 @@ Disable TUI mode, returning to the console interpreter.
 @kindex info win
 List and give the size of all displayed windows.
 
-@item layout next
+@item layout @var{name}
 @kindex layout
+Changes which TUI windows are displayed.  In each layout the command
+window is always displayed, the value of @var{name} controls which
+additional windows are also displayed, and can be any of the
+following:
+
+@table @code
+@item next
 Display the next layout.
 
-@item layout prev
+@item prev
 Display the previous layout.
 
-@item layout src
-Display the source window only.
+@item src
+Display the source and command windows.
 
-@item layout asm
-Display the assembly window only.
+@item asm
+Display the assembly and command windows.
 
-@item layout split
-Display the source and assembly window.
+@item split
+Display the source, assembly, and command windows.
 
-@item layout regs
-Display the register window together with the source or assembly window.
+@item regs
+When in @code{src} or @code{asm} layout the register window is
+displayed in addition to the existing source or assembler window.
+When in @code{split} layout then the register and assembler windows
+are displayed.  The command window is always displayed.
+@end table
 
-@item focus next
+@item focus @var{name}
 @kindex focus
+Changes which TUI window is currently active for scrolling.  The value
+of @var{name} can be any of the following:
+
+@table @code
+@item next
 Make the next window active for scrolling.
 
-@item focus prev
+@item prev
 Make the previous window active for scrolling.
 
-@item focus src
+@item src
 Make the source window active for scrolling.
 
-@item focus asm
+@item asm
 Make the assembly window active for scrolling.
 
-@item focus regs
+@item regs
 Make the register window active for scrolling.
 
-@item focus cmd
+@item cmd
 Make the command window active for scrolling.
+@end table
 
 @item refresh
 @kindex refresh
-- 
2.4.0

Re: [PATCH] gdb: Rewrite documentation for layout and focus commands.

[Eli Zaretskii]

> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Cc: Andrew Burgess <andrew.burgess@embecosm.com>
> Date: Mon,  6 Jul 2015 14:15:39 +0100
> 
> The following patch changes the documentation for the layout and focus
> commands.  Though I have extended the documentation for layout
> slightly most of this patch is really about reformatting the layout of
> the documentation.
> 
> The change is really just my personal preference, but I think the new
> layout is clearer, do people agree?

This is fine with me, but please be consistent in your style.  For
example:

> +@item regs
> +When in @code{src} or @code{asm} layout the register window is
> +displayed in addition to the existing source or assembler window.
> +When in @code{split} layout then the register and assembler windows
> +are displayed.  The command window is always displayed.

This uses passive tense "is displayed", whereas all the rest use
"Display", which is shorter and more in line with how we describe
settings.

> +@item focus @var{name}
>  @kindex focus
> +Changes which TUI window is currently active for scrolling.  The value
> +of @var{name} can be any of the following:

"The value of @var{name}" sounds strange.  I suggest The @var{name}
parameter can be any of ...".

OK with those changes.

Thanks.