[PATCH] [gdb/doc]: Updated manpages to be consistent with help

[PATCH] [gdb/doc]: Updated manpages to be consistent with help

[Bruno Larsen]

Updated manpages to be consistent with help information provided by the
binary. The main changes are Making all long-form options have '--',
instead of a single '-' and added most of the missing options to the
manpage.
---
 gdb/doc/gdb.texinfo | 136 +++++++++++++++++++++++++++++++-------------
 1 file changed, 97 insertions(+), 39 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index c156a1d6739..cbf72d20e20 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -47077,14 +47077,7 @@ switch (die->tag)
 @c man title gdb The GNU Debugger
 
 @c man begin SYNOPSIS gdb
-gdb [@option{-help}] [@option{-nh}] [@option{-nx}] [@option{-q}]
-[@option{-batch}] [@option{-cd=}@var{dir}] [@option{-f}]
-[@option{-b}@w{ }@var{bps}]
-    [@option{-tty=}@var{dev}] [@option{-s} @var{symfile}]
-[@option{-e}@w{ }@var{prog}] [@option{-se}@w{ }@var{prog}]
-[@option{-c}@w{ }@var{core}] [@option{-p}@w{ }@var{procID}]
-    [@option{-x}@w{ }@var{cmds}] [@option{-d}@w{ }@var{dir}]
-[@var{prog}|@var{prog} @var{procID}|@var{prog} @var{core}]
+gdb [OPTIONS] [@var{prog}|@var{prog} @var{procID}|@var{prog} @var{core}]
 @c man end
 
 @c man begin DESCRIPTION gdb
@@ -47148,8 +47141,8 @@ Here are some of the most frequently needed @value{GDBN} commands:
 
 @c pod2man highlights the right hand side of the @item lines.
 @table @env
-@item break [@var{file}:]@var{function}
-Set a breakpoint at @var{function} (in @var{file}).
+@item break [@var{file}:][@var{function}|@var{line}]
+Set a breakpoint at @var{function} or @var{line} (in @var{file}).
 
 @item run [@var{arglist}]
 Start your program (with @var{arglist}, if specified).
@@ -47197,72 +47190,76 @@ as the @code{gdb} entry in the @code{info} program.
 Any arguments other than options specify an executable
 file and core file (or process ID); that is, the first argument
 encountered with no
-associated option flag is equivalent to a @option{-se} option, and the second,
+associated option flag is equivalent to a @option{--se} option, and the second,
 if any, is equivalent to a @option{-c} option if it's the name of a file.
 Many options have
 both long and short forms; both are shown here.  The long forms are also
 recognized if you truncate them, so long as enough of the option is
-present to be unambiguous.  (If you prefer, you can flag option
-arguments with @option{+} rather than @option{-}, though we illustrate the
-more usual convention.)
+present to be unambiguous.
 
 All the options and command line arguments you give are processed
 in sequential order.  The order makes a difference when the @option{-x}
 option is used.
 
 @table @env
-@item -help
+@item --help
 @itemx -h
 List all options, with brief explanations.
 
-@item -symbols=@var{file}
-@itemx -s @var{file}
-Read symbol table from file @var{file}.
+@item --symbols=@var{symfile}
+@itemx -s @var{symfile}
+Read symbol table from file @var{symfile}.
 
-@item -write
+@item --write
 Enable writing into executable and core files.
 
-@item -exec=@var{file}
-@itemx -e @var{file}
-Use file @var{file} as the executable file to execute when
+@item --exec=@var{execfile}
+@itemx -e @var{execfile}
+Use file @var{execfile} as the executable file to execute when
 appropriate, and for examining pure data in conjunction with a core
 dump.
 
-@item -se=@var{file}
+@item --se=@var{file}
 Read symbol table from file @var{file} and use it as the executable
 file.
 
-@item -core=@var{file}
-@itemx -c @var{file}
-Use file @var{file} as a core dump to examine.
+@item --core=@var{corefile}
+@itemx -c @var{corefile}
+Use file @var{corefile} as a core dump to examine.
 
-@item -command=@var{file}
+@item --command=@var{file}
 @itemx -x @var{file}
 Execute @value{GDBN} commands from file @var{file}.
 
+@item --eval-command=@var{command}
 @item -ex @var{command}
 Execute given @value{GDBN} @var{command}.
 
-@item -directory=@var{directory}
-@itemx -d @var{directory}
-Add @var{directory} to the path to search for source files.
+@item --init-eval-command=@var{command}
+@item -iex
+Execute @value{GDBN} @var{command} before loading the inferior.
 
-@item -nh
+@item --directory=@var{DIR}
+@itemx -d @var{DIR}
+Add @var{DIR} to the path to search for source files.
+
+@item --nh
 Do not execute commands from @file{~/.config/gdb/gdbinit},
 @file{~/.gdbinit}, @file{~/.config/gdb/gdbearlyinit}, or
 @file{~/.gdbearlyinit}
 
-@item -nx
+@item --nx
 @itemx -n
 Do not execute commands from any @file{.gdbinit} or
 @file{.gdbearlyinit} initialization files.
 
-@item -quiet
+@item --quiet
+@item --silent
 @itemx -q
 ``Quiet''.  Do not print the introductory and copyright messages.  These
 messages are also suppressed in batch mode.
 
-@item -batch
+@item --batch
 Run in batch mode.  Exit with status @code{0} after processing all the command
 files specified with @option{-x} (and @file{.gdbinit}, if not inhibited).
 Exit with nonzero status if an error occurs in executing the @value{GDBN}
@@ -47280,11 +47277,69 @@ Program exited normally.
 (which is ordinarily issued whenever a program running under @value{GDBN} control
 terminates) is not issued when running in batch mode.
 
-@item -cd=@var{directory}
-Run @value{GDBN} using @var{directory} as its working directory,
+@item --batch-silent
+Run in batch mode, just like @option{--batch}, but totally silent. All @value{GDBN}
+output is supressed (stderr is unaffected). This is much quieter than
+@option{--silent} and would be useless for an interactive session.
+
+This is particularly useful when using targets that give 'Loading section'
+messages, for example.
+
+Note that targets that give their ourpur via GDB, as opposed to writting
+directly to stdout, will also be made silent.
+
+@item --args @var{prog} [@var{arglist}]
+Change interpretation of command line so that arguments following this
+option are passed as arguments to the inferior. As an example, take
+the following command:
+
+@smallexample
+gdb ./a.out -q
+@end smallexample
+
+Will start GDB with @option{-q}, not printing the introductory message. On
+the other hand, using:
+
+@smallexample
+gdb --args ./a.out -q
+@end smallexample
+
+Starts GDB with the introductory message, and passes the option to the inferior.
+
+@item --pid=@var{PID}
+Attach GDB to an already running program, with the PID @var{PID}.
+
+@item --tui
+Opens the terminal user interface.
+
+@item --readnow
+Read all symbols from the given symfile on the first access.
+
+@item --readnever
+Do not read symbol files.
+
+@item --dbx
+Run in DBX compatibility mode.
+
+@item --return-child-result
+@value{GDBN}'s exit code will be the same as the child's exit code.
+
+@item --configuration
+Prints details about GDB configuration and then exit.
+
+@item --version
+Print version information and then exit.
+
+@item --cd=@var{DIR}
+Run @value{GDBN} using @var{DIR} as its working directory,
 instead of the current directory.
 
-@item -fullname
+@item --data-directory=@var{DIR}
+@item -D
+Run @value{GDBN} using @var{DIR} as its data directory. The data
+directory is where @value{GDBN} searches for its auxiliary files.
+
+@item --fullname
 @itemx -f
 Emacs sets this option when it runs @value{GDBN} as a subprocess.  It tells
 @value{GDBN} to output the full file name and line number in a standard,
@@ -47295,11 +47350,14 @@ and character position separated by colons, and a newline.  The
 Emacs-to-@value{GDBN} interface program uses the two @samp{\032}
 characters as a signal to display the source code for the frame.
 
-@item -b @var{bps}
+@item -b @var{BAUDRATE}
 Set the line speed (baud rate or bits per second) of any serial
 interface used by @value{GDBN} for remote debugging.
 
-@item -tty=@var{device}
+@item -l @var{TIMEOUT}
+Set timeout, in seconds, for remote debugging.
+
+@item --tty=@var{device}
 Run using @var{device} for your program's standard input and output.
 @end table
 @c man end
-- 
2.27.0

Re: [PATCH] [gdb/doc]: Updated manpages to be consistent with help

[Eli Zaretskii]

> Date: Wed, 13 Oct 2021 10:04:09 -0300
> From: Bruno Larsen via Gdb-patches <gdb-patches@sourceware.org>
> 
> Updated manpages to be consistent with help information provided by the
> binary. The main changes are Making all long-form options have '--',
> instead of a single '-' and added most of the missing options to the
> manpage.

Thanks.  The replacement of '-' by '--' are mechanical and don't need
any approval.

Many other changes replace something like this:

  Use @file{file} as SOMETHING.

with something like this:

  Use file @file{somefile} as SOMETHING.

I must confess that I prefer the former form, because it makes the
text more concise and easier to read, by avoiding one more "file".

> -@item -nh
> +@item --directory=@var{DIR}
> +@itemx -d @var{DIR}
> +Add @var{DIR} to the path to search for source files.

The string inside @var{..} should never be upper-case.  (Yes, I know
this was in the original text.)

Also, here I'd prefer

   Add @var{directory} to the path to search for source files.

because "DIR" doesn't necessarily speak for its being a directory.

> -@item -cd=@var{directory}
> -Run @value{GDBN} using @var{directory} as its working directory,
> +@item --batch-silent
> +Run in batch mode, just like @option{--batch}, but totally silent. All @value{GDBN}
> +output is supressed (stderr is unaffected). This is much quieter than
                                             ^^
Two spaces between sentences, please.

> +This is particularly useful when using targets that give 'Loading section'
                                                            ^^^^^^^^^^^^^^^^^
This should be in @samp, not in literal quotes.

> +Note that targets that give their ourpur via GDB, as opposed to writting
                                                ^^^
@value{GDBN}

> +directly to stdout, will also be made silent.

"stdout" should be in @code.  Or use "standard output" instead.

> +@item --args @var{prog} [@var{arglist}]
> +Change interpretation of command line so that arguments following this
> +option are passed as arguments to the inferior. As an example, take
                                                 ^^
Two spaces.

> +Will start GDB with @option{-q}, not printing the introductory message. On
              ^^^                                                        ^^
@value{GDBN}, and two spaces.

> +Starts GDB with the introductory message, and passes the option to the inferior.

@value{GDBN}

> +@item --pid=@var{PID}
> +Attach GDB to an already running program, with the PID @var{PID}.

Likewise.  Also, @var{PID} should be @var{pid}.

> +@item --configuration
> +Prints details about GDB configuration and then exit.

@value{GDBN}

> +@item --cd=@var{DIR}
> +Run @value{GDBN} using @var{DIR} as its working directory,
>  instead of the current directory.

Please replace "DIR" with "directory".

> -@item -fullname
> +@item --data-directory=@var{DIR}
> +@item -D
> +Run @value{GDBN} using @var{DIR} as its data directory. The data
> +directory is where @value{GDBN} searches for its auxiliary files.

Likewise.

> -@item -b @var{bps}
> +@item -b @var{BAUDRATE}

Uppercase @var again.

> -@item -tty=@var{device}
> +@item -l @var{TIMEOUT}
> +Set timeout, in seconds, for remote debugging.

And here.

Thanks.

Re: [PATCH] [gdb/doc]: Updated manpages to be consistent with help

[Bruno Larsen]

On 10/13/21 10:50 AM, Eli Zaretskii wrote:
>> Date: Wed, 13 Oct 2021 10:04:09 -0300
>> From: Bruno Larsen via Gdb-patches <gdb-patches@sourceware.org>
>>
>> Updated manpages to be consistent with help information provided by the
>> binary. The main changes are Making all long-form options have '--',
>> instead of a single '-' and added most of the missing options to the
>> manpage.
> 
> Thanks.  The replacement of '-' by '--' are mechanical and don't need
> any approval.
> 
> Many other changes replace something like this:
> 
>    Use @file{file} as SOMETHING.
> 
> with something like this:
> 
>    Use file @file{somefile} as SOMETHING.
> 
> I must confess that I prefer the former form, because it makes the
> text more concise and easier to read, by avoiding one more "file".
> 

Thanks for the review. This change in specific, I understand why you may not be a fan, but the idea was to sync between manpages and --help, and since help calls those "somefile" instead of just "file" I thought it was worth doing. I can roll them back, but I think the --help text should be changed to be the same generic file. Same goes for DIR and directory, which you mention below. Up to your preferences which of those I do.

I'll implement to all the other style changes you mentioned. It could be worth adding them to the Documentation writing standard (https://sourceware.org/gdb/wiki/Internals%20GDB-Doc-Standards) since that page is almost empty.

>> -@item -nh
>> +@item --directory=@var{DIR}
>> +@itemx -d @var{DIR}
>> +Add @var{DIR} to the path to search for source files.
> 
> The string inside @var{..} should never be upper-case.  (Yes, I know
> this was in the original text.)
> 
> Also, here I'd prefer
> 
>     Add @var{directory} to the path to search for source files.
> 
> because "DIR" doesn't necessarily speak for its being a directory.
> 


-- 
Cheers!
Bruno Larsen

Re: [PATCH] [gdb/doc]: Updated manpages to be consistent with help

[Sergio Durigan Junior]

On Wednesday, October 13 2021, Bruno Larsen via Gdb-patches wrote:

> Updated manpages to be consistent with help information provided by the
> binary. The main changes are Making all long-form options have '--',
> instead of a single '-' and added most of the missing options to the
> manpage.

You might want to mention/fix
https://sourceware.org/bugzilla/show_bug.cgi?id=23965 and likely other
related manpage bugs in this commit.

Thanks,

-- 
Sergio
GPG key ID: 237A 54B1 0287 28BF 00EF  31F4 D0EB 7628 65FC 5E36
Please send encrypted e-mail if possible
https://sergiodj.net/

Re: [PATCH] [gdb/doc]: Updated manpages to be consistent with help

[Bruno Larsen]

On 10/13/21 12:30 PM, Sergio Durigan Junior wrote:
> On Wednesday, October 13 2021, Bruno Larsen via Gdb-patches wrote:
> 
>> Updated manpages to be consistent with help information provided by the
>> binary. The main changes are Making all long-form options have '--',
>> instead of a single '-' and added most of the missing options to the
>> manpage.
> 
> You might want to mention/fix
> https://sourceware.org/bugzilla/show_bug.cgi?id=23965 and likely other
> related manpage bugs in this commit.
> 
> Thanks,
> 
Good catch! I added this bug and https://sourceware.org/bugzilla/show_bug.cgi?id=10619

The other ones were unrelated (documentation of ?? and reordering of options to be alphabetical)

-- 
Cheers!
Bruno Larsen

Re: [PATCH] [gdb/doc]: Updated manpages to be consistent with help

[Philippe Waroquiers]

Note that I started a patch to have the options consistently using -- 

But as GDB accepts various layout for options (such as -thisone or --thisone),
it was not very clear it that was a good thing to do.
Pedro e.g. commented that GDB does not use the concept of 'short' and 'long' options.

Finally, as I understand, the decision was rather to use as cannnical form
  -thisone
 (in the doc and on line help)
and so the manual should then also be aligned.

Sadly, I had no time to finalize the patch (i.e. to rather systematically use
the single dash convention).
But this patch seems then not to go into what I think is the last agreed direction.

See the initial RFC in 
https://sourceware.org/pipermail/gdb-patches/2021-June/179587.html
and RFA in
https://sourceware.org/pipermail/gdb-patches/2021-June/179834.html

Thanks
Philippe





On Thu, 2021-10-14 at 10:10 -0300, Bruno Larsen via Gdb-patches wrote:
> On 10/13/21 12:30 PM, Sergio Durigan Junior wrote:
> > On Wednesday, October 13 2021, Bruno Larsen via Gdb-patches wrote:
> > 
> > > Updated manpages to be consistent with help information provided by the
> > > binary. The main changes are Making all long-form options have '--',
> > > instead of a single '-' and added most of the missing options to the
> > > manpage.
> > 
> > You might want to mention/fix
> > https://sourceware.org/bugzilla/show_bug.cgi?id=23965 and likely other
> > related manpage bugs in this commit.
> > 
> > Thanks,
> > 
> Good catch! I added this bug and https://sourceware.org/bugzilla/show_bug.cgi?id=10619
> 
> The other ones were unrelated (documentation of ?? and reordering of options to be alphabetical)
> 

Re: [PATCH] [gdb/doc]: Updated manpages to be consistent with help

[Bruno Larsen]

On 10/14/21 15:56, Philippe Waroquiers wrote:
> Note that I started a patch to have the options consistently using --
> 
> But as GDB accepts various layout for options (such as -thisone or --thisone),
> it was not very clear it that was a good thing to do.
> Pedro e.g. commented that GDB does not use the concept of 'short' and 'long' options.
> 
> Finally, as I understand, the decision was rather to use as cannnical form
>    -thisone
>   (in the doc and on line help)
> and so the manual should then also be aligned.
> 
> Sadly, I had no time to finalize the patch (i.e. to rather systematically use
> the single dash convention).
> But this patch seems then not to go into what I think is the last agreed direction.
> 
> See the initial RFC in
> https://sourceware.org/pipermail/gdb-patches/2021-June/179587.html
> and RFA in
> https://sourceware.org/pipermail/gdb-patches/2021-June/179834.html
> 
> Thanks
> Philippe
> 

Hi! I didn't see this patch when writing my own, sorry.

As for not going the agreed direction, it didn't sounds "agreed" to me, since Eli agreed with documenting '--' while Pedro preferred '-'. I agree with the argument that GDB doesn't accept short options, since you can't combine them, but the help page still shows the abbreviated versions with a single dash and longer versions with '--' and that causes confusion for users. What the patches are supposed to do is make those 2 pages consistent and avoid user confusion, keeping them as-is because the developers know it makes more sense doesn't fix confusion.

My proposed solution is: Let's make them consistent with help, all longer options having '--', use your text explaining that GDB accepts all 8 versions of options despite how they are written, but change it to call "abbreviated" and "longer" options instead, to avoid the "short option" confusion that Pedro has brought up. Does that sound reasonable?

-- 
Cheers!
Bruno Larsen

Re: [PATCH] [gdb/doc]: Updated manpages to be consistent with help

[Philippe Waroquiers]

On Fri, 2021-10-15 at 10:27 -0300, Bruno Larsen wrote:
> On 10/14/21 15:56, Philippe Waroquiers wrote:
> > Note that I started a patch to have the options consistently using --
> > 
> > But as GDB accepts various layout for options (such as -thisone or --thisone),
> > it was not very clear it that was a good thing to do.
> > Pedro e.g. commented that GDB does not use the concept of 'short' and 'long' options.
> > 
> > Finally, as I understand, the decision was rather to use as cannnical form
> >    -thisone
> >   (in the doc and on line help)
> > and so the manual should then also be aligned.
> > 
> > Sadly, I had no time to finalize the patch (i.e. to rather systematically use
> > the single dash convention).
> > But this patch seems then not to go into what I think is the last agreed direction.
> > 
> > See the initial RFC in
> > https://sourceware.org/pipermail/gdb-patches/2021-June/179587.html
> > and RFA in
> > https://sourceware.org/pipermail/gdb-patches/2021-June/179834.html
> > 
> > Thanks
> > Philippe
> > 
> 
> Hi! I didn't see this patch when writing my own, sorry.
> 
> As for not going the agreed direction, it didn't sounds "agreed" to me, since Eli agreed with documenting '--' while Pedro preferred '-'. I agree with the argument that GDB doesn't accept short options, since you can't combine them, but the help page still shows the abbreviated versions with a single dash and longer versions with '--' and that causes confusion for users. What the patches are supposed to do is make those 2 pages consistent and avoid user confusion, keeping them as-is because the developers know it makes more sense doesn't fix confusion.
> 
> My proposed solution is: Let's make them consistent with help, all longer options having '--', use your text explaining that GDB accepts all 8 versions of options despite how they are written, but change it to call "abbreviated" and "longer" options instead, to avoid the "short option" confusion that Pedro has brought up. Does that sound reasonable?
> 

See also the feedback of Joel.
https://sourceware.org/pipermail/gdb-patches/2021-August/181294.html

Philippe

Re: [PATCH] [gdb/doc]: Updated manpages to be consistent with help

[Bruno Larsen]

On 10/16/21 08:44, Philippe Waroquiers wrote:
> On Fri, 2021-10-15 at 10:27 -0300, Bruno Larsen wrote:
>> On 10/14/21 15:56, Philippe Waroquiers wrote:
>>> Note that I started a patch to have the options consistently using --
>>>
>>> But as GDB accepts various layout for options (such as -thisone or --thisone),
>>> it was not very clear it that was a good thing to do.
>>> Pedro e.g. commented that GDB does not use the concept of 'short' and 'long' options.
>>>
>>> Finally, as I understand, the decision was rather to use as cannnical form
>>>     -thisone
>>>    (in the doc and on line help)
>>> and so the manual should then also be aligned.
>>>
>>> Sadly, I had no time to finalize the patch (i.e. to rather systematically use
>>> the single dash convention).
>>> But this patch seems then not to go into what I think is the last agreed direction.
>>>
>>> See the initial RFC in
>>> https://sourceware.org/pipermail/gdb-patches/2021-June/179587.html
>>> and RFA in
>>> https://sourceware.org/pipermail/gdb-patches/2021-June/179834.html
>>>
>>> Thanks
>>> Philippe
>>>
>>
>> Hi! I didn't see this patch when writing my own, sorry.
>>
>> As for not going the agreed direction, it didn't sounds "agreed" to me, since Eli agreed with documenting '--' while Pedro preferred '-'. I agree with the argument that GDB doesn't accept short options, since you can't combine them, but the help page still shows the abbreviated versions with a single dash and longer versions with '--' and that causes confusion for users. What the patches are supposed to do is make those 2 pages consistent and avoid user confusion, keeping them as-is because the developers know it makes more sense doesn't fix confusion.
>>
>> My proposed solution is: Let's make them consistent with help, all longer options having '--', use your text explaining that GDB accepts all 8 versions of options despite how they are written, but change it to call "abbreviated" and "longer" options instead, to avoid the "short option" confusion that Pedro has brought up. Does that sound reasonable?
>>
> 
> See also the feedback of Joel.
> https://sourceware.org/pipermail/gdb-patches/2021-August/181294.html
> 
> Philippe
> 
> 
Having looked at that e-mail, I think the new version is conforming to the agreed direction of documenting that GDB doesn't care about - or --, but still document it as traditional argument handling does: https://sourceware.org/pipermail/gdb-patches/2021-October/182632.html

Thanks for the resources and for looking at the patch

-- 
Cheers!
Bruno Larsen