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

[Bruno Larsen via Gdb-patches <gdb-patches@sourceware.org>]

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