diff mbox

Share options between info and man page

Message ID CADNgcEyi=PBbjzgK3MA=FM8QjWXz_jv-KuXYe5b4-pu+LUY6xA@mail.gmail.com
State New
Headers show

Commit Message

Mingjie Xing June 9, 2014, 8:39 a.m. UTC
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

Comments

Eli Zaretskii June 9, 2014, 2:52 p.m. UTC | #1
> 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.
Mingjie Xing June 10, 2014, 12:46 a.m. UTC | #2
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
Eli Zaretskii June 10, 2014, 2:52 a.m. UTC | #3
> 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.
Mingjie Xing June 10, 2014, 7 a.m. UTC | #4
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
Eli Zaretskii June 10, 2014, 5:56 p.m. UTC | #5
> 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.
diff mbox

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a0fb66d..7b887e7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -918,6 +918,8 @@  in sequential order.  The order makes a difference when the
 * Startup::                     What @value{GDBN} does during startup
 @end menu
 
+@c man begin OPTIONS gdb
+
 @node File Options
 @subsection Choosing Files
 
@@ -1374,6 +1376,7 @@  port of @value{GDBN} uses the standard name, but if it finds a
 @file{gdb.ini} file in your home directory, it warns you about that
 and suggests to rename the file to the standard name.
 
+@c man end
 
 @node Quitting GDB
 @section Quitting @value{GDBN}
@@ -39837,113 +39840,7 @@  as the @code{gdb} entry in the @code{info} program.
 @end ifset
 @c man end
 
-@c man begin OPTIONS gdb
-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,
-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.)
-
-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
-@itemx -h
-List all options, with brief explanations.
-
-@item -symbols=@var{file}
-@itemx -s @var{file}
-Read symbol table from file @var{file}.
-
-@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
-appropriate, and for examining pure data in conjunction with a core
-dump.
-
-@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 -command=@var{file}
-@itemx -x @var{file}
-Execute @value{GDBN} commands from file @var{file}.
-
-@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 -nh
-Do not execute commands from @file{~/.gdbinit}.
-
-@item -nx
-@itemx -n
-Do not execute commands from any @file{.gdbinit} initialization files.
-
-@item -quiet
-@itemx -q
-``Quiet''.  Do not print the introductory and copyright messages.  These
-messages are also suppressed in batch mode.
-
-@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}
-commands in the command files.
-
-Batch mode may be useful for running @value{GDBN} as a filter, for example to
-download and run a program on another computer; in order to make this
-more useful, the message
-
-@smallexample
-Program exited normally.
-@end smallexample
-
-@noindent
-(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,
-instead of the current directory.
-
-@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,
-recognizable fashion each time a stack frame is displayed (which
-includes each time the program stops).  This recognizable format looks
-like two @samp{\032} characters, followed by the file name, line number
-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}
-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}
-Run using @var{device} for your program's standard input and output.
-@end table
-@c man end
+@xref{Invoking GDB}, for options.
 
 @c man begin SEEALSO gdb
 @ifset man