Re: [PATCH 24/24] NEWS and manual changes for command options changes

[Pedro Alves <palves@redhat.com>]

On 5/23/19 5:31 AM, Eli Zaretskii wrote:>> From: Pedro Alves <palves@redhat.com>
>> Date: Wed, 22 May 2019 21:53:27 +0100
>>
>> gdb/ChangeLog:
>> yyyy-mm-dd  Pedro Alves  <palves@redhat.com>
>>
>> 	* NEWS (New commands): Mention "maint test-options
>> 	require-delimiter", "maint test-options unknown-is-error", "maint
>> 	test-options unknown-is-operand" and "maint show
>> 	test-options-completion-result".
>> 	(New command options, command completion): New section.
>> 	(Completion improvements): New section.
>> 	Mention that you can abbreviate "unlimited".
>>
>> gdb/doc/ChangeLog:
>> yyyy-mm-dd  Pedro Alves  <palves@redhat.com>
>>
>> 	* gdb.texinfo (Command Completion): Mention command options too.
>> 	(Command Options): New node.
>> 	(Threads): Add anchors.  Extend descriptions of the "taas" and
>> 	"tfaas" commands.
>> 	(Backtrace): Describe new options of the "backtrace" command.  Add
>> 	anchors.
>> 	(Frame Apply): Describe new options of the "frame apply" and
>> 	"faas" commands.  Add anchors.
>> 	(Data): Describe new options of the "print" command.  Add anchors.
>> 	(Compiling and Injecting Code): Mention options of the "compile
>> 	print" command.
>> 	(Maintenance Commands): Mention "maint test-options" subcommands
>> 	and the "maint show test-options-completion-result" command.
> 
> Thanks.  

Thank you.


>  A couple of minor comments.
> 
>> +apply all} command.  See @ref{thread apply all}.
> 
> I'd prefer @xref to "See @ref" at the beginning of a sentence.
> 
>> +apply} command.  See @ref{frame apply}.
> 
> Same here.
> 
>> +@item -past-main [@code{on}|@code{off}]
>> +Set whether backtraces should continue past "main".  Related setting:
> 
> "main" is a symbol, so please use @code{main}.
> 
>> +@item -entry-values @code{no}|@code{only}|@code{preferred}|@code{if-needed}|@code{both}|@code{compact}|@code{default}
> 
> Does this long line look reasonable in print?  If not, perhaps using
> just one meta-argument, followed by a table of possible values, would
> be better?

Looks good to me in pdf form.  It all fits in a single line.

> 
>> +@item -past-main [@code{on}|@code{off}]
>> +Whether backtraces should continue past "main".
> 
> Same issue with "main".
> 
>> +apply} command.  See @ref{frame apply}.
> 
> "See @ref" again.
> 
>> +@item -object [@code{on}|@code{off}]
>> +Set printing C++ virtual function tables.  Related setting: @ref{set
>                 ^^^
> C@t{++}, please (here and elsewhere in the patch).
> 
>> +@item -repeats @var{number-of-repeats}|@code{unlimited}
>> +Set threshold for repeated print elements. "unlimited" causes all
>                                             ^^
> Two spaces between sentences.  Also, "unlimited" at the sentence
> beginning looks awkward without capitalization.
> 

Hmm, "unlimited" is a literal, so I think we should use @code for it.
Is is OK this way?  I can rephrase a little to avoid @{unlimited} at
the beginning of the sentence, but I'm trying to be concise here,
since this is meant to be a brief outlook into the options, with a
reference to the "set" command anchor for more info.

Here are the changes I'm making to address your review:

---
 gdb/doc/gdb.texinfo | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a7f92d1195d..ff06e7ceaa7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -3293,7 +3293,7 @@ Shortcut for @code{thread apply all -s [@var{option}]@dots{} @var{command}}.
 Applies @var{command} on all threads, ignoring errors and empty output.
 
 The @code{taas} command accepts the same options as the @code{thread
-apply all} command.  See @ref{thread apply all}.
+apply all} command.  @xref{thread apply all}.
 
 @kindex tfaas
 @cindex apply a command to all frames of all threads (ignoring errors and empty output)
@@ -3315,7 +3315,7 @@ is, using:
 @end smallexample
 
 The @code{tfaas} command accepts the same options as the @code{frame
-apply} command.  See @ref{frame apply}.
+apply} command.  @xref{frame apply}.
 
 @kindex thread name
 @cindex name a thread
@@ -7593,7 +7593,7 @@ backtrace} and @code{set print} subcommands:
 
 @table @code
 @item -past-main [@code{on}|@code{off}]
-Set whether backtraces should continue past "main".  Related setting:
+Set whether backtraces should continue past @code{main}.  Related setting:
 @ref{set backtrace past-main}.
 
 @item -past-entry [@code{on}|@code{off}]
@@ -8087,7 +8087,7 @@ allow overriding relevant @code{set backtrace} settings:
 
 @table @code
 @item -past-main [@code{on}|@code{off}]
-Whether backtraces should continue past "main".
+Whether backtraces should continue past @code{main}.
 Related setting: @ref{set backtrace past-main}.
 
 @item -past-entry [@code{on}|@code{off}]
@@ -8179,7 +8179,7 @@ is, using:
 @end smallexample
 
 The @code{faas} command accepts the same options as the @code{frame
-apply} command.  See @ref{frame apply}.
+apply} command.  @xref{frame apply}.
 
 Note that the command @code{tfaas @var{command}} applies @var{command}
 on all frames of all threads.  See @xref{Threads,,Threads}.
@@ -9320,9 +9320,9 @@ Set printing of array indexes.
 Related setting: @ref{set print array-indexes}.
 
 @item -elements @var{number-of-elements}|@code{unlimited}
-Set limit on string chars or array elements to print.  "unlimited"
-causes there to be no limit.  Related setting: @ref{set print
-elements}.
+Set limit on string chars or array elements to print.
+@code{unlimited} causes there to be no limit.  Related setting:
+@ref{set print elements}.
 
 @item -max-depth @var{depth}|@code{unlimited}
 Set the threshold after which nested structures are replaced with
@@ -9333,20 +9333,20 @@ Set printing of char arrays to stop at first null char.  Related
 setting: @ref{set print null-stop}.
 
 @item -object [@code{on}|@code{off}]
-Set printing C++ virtual function tables.  Related setting: @ref{set
-print object}.
+Set printing C@t{++} virtual function tables.  Related setting:
+@ref{set print object}.
 
 @item -pretty [@code{on}|@code{off}]
 Set pretty formatting of structures.  Related setting: @ref{set print
 pretty}.
 
 @item -repeats @var{number-of-repeats}|@code{unlimited}
-Set threshold for repeated print elements. "unlimited" causes all
-elements to be individually printed.  Related setting: @ref{set print
-repeats}.
+Set threshold for repeated print elements.  @code{unlimited} causes
+all elements to be individually printed.  Related setting: @ref{set
+print repeats}.
 
 @item -static-members [@code{on}|@code{off}]
-Set printing C++ static members.  Related setting: @ref{set print
+Set printing C@t{++} static members.  Related setting: @ref{set print
 static-members}.
 
 @item -symbol [@code{on}|@code{off}]
-- 
2.14.5