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

Pedro Alves
2019-05-23T15:01:28Z

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