Re: [patch] Share options between info and man page

Mingjie Xing
2014-06-10T07:00:37Z

Hello,

2014-06-10 10:52 GMT+08:00 Eli Zaretskii <eliz@gnu.org>:
>> From: Mingjie Xing <mingjie.xing@gmail.com>
>> Date: Tue, 10 Jun 2014 08:46:10 +0800
>> Cc: gdb-patches@sourceware.org
>>
>> 2014-06-09 22:52 GMT+08:00 Eli Zaretskii <eliz@gnu.org>:
>> > The text of these two portions is different, so you are actually
>> > changing the man page contents. Also, the @node and @section lines
>> > are probably inappropriate for a man page.
>>
>> Yes, but you can see that the man page contents are almost same with
>> those sections.
>
> Then please also suggest changes to make them exactly the same. I'm
> OK with making the maintenance burden easier, but I don't want to lose
> content.

I made a compare and find that only one paragraph and one option are
unique to man page:

"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."

and

"@item -help
@itemx -h
List all options, with brief explanations."

I've preserved them and moved to 'File Options'.

On the other hand, there are many options missing in man page which
can be resolved by sharing.

>> For an example, gcc's man page and info page use the
>> same file 'invoke.texi' which includes @node and @section lines.
>
> I'm sorry, but GCC's example is unlikely to convince me, because I
> consider the GCC documentation to be one of the worst examples in the
> GNU project. I can never find useful up to date information there
> when I'm looking for it.
>
> It should be easy to keep the @node and @chapter out of the man page.

Done.

doc/ChangeLog:

* gdb.texinfo (Man Pages): Remove the content of man OPTIONS gdb, add
a cross reference to 'Invoking GDB'.
(Invoking GDB): Share the option sub-sections with man OPTIONS gdb,
move the uniqe part of man to here.

Best regards,
Mingjie