Share options between info and man page

  Hello,

As we can see, gdb.texinfo has two separate option sections for info
page and man page. This causes duplication and is hard to maintain.
The patch removes the part in man page, and shares the sections from
info page. Is it OK?

doc/ChangeLog

        * gdb.texinfo (Man Pages): Remove the content of man OPTIONS gdb, add
        a cross reference to 'Invoking GDB'.
        (Invoking GDB): Enclosure the option sub-sections in man OPTIONS gdb.


Best regards
Mingjie
  

> From: Mingjie Xing <mingjie.xing@gmail.com>
> Date: Mon, 9 Jun 2014 16:39:53 +0800
> 
> As we can see, gdb.texinfo has two separate option sections for info
> page and man page. This causes duplication and is hard to maintain.
> The patch removes the part in man page, and shares the sections from
> info page. Is it OK?

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.
  

Hi,

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. For an example, gcc's man page and info page use the
same file 'invoke.texi' which includes @node and @section lines.

Thanks,
Mingjie
  

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

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

Thanks.
  

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
  

> From: Mingjie Xing <mingjie.xing@gmail.com>
> Date: Tue, 10 Jun 2014 15:00:12 +0800
> Cc: gdb-patches@sourceware.org
> 
> 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.

Thanks.  This looks good to me.  If no one objects, it should go in
soon.