[patch] Share options between info and man page

[patch] Share options between info and man page

[Mingjie Xing]

[-- Attachment #1: Type: text/plain, Size: 475 bytes --]

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

[-- Attachment #2: gdb-man.patch --]
[-- Type: text/x-patch, Size: 4516 bytes --]

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

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

[Eli Zaretskii]

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

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

[Mingjie Xing]

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

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

[Eli Zaretskii]

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

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

[Mingjie Xing]

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

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

[Mingjie Xing]

[-- Attachment #1: Type: text/plain, Size: 29 bytes --]

Sorry for the missing patch.

[-- Attachment #2: gdb-man.patch --]
[-- Type: text/x-patch, Size: 5954 bytes --]

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a0fb66d..b9675af 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -921,6 +921,8 @@ in sequential order.  The order makes a difference when the
 @node File Options
 @subsection Choosing Files
 
+@c man begin OPTIONS gdb
+
 When @value{GDBN} starts, it reads any arguments other than options as
 specifying an executable file and core file (or process ID).  This is
 the same as if the arguments were specified by the @samp{-se} and
@@ -945,11 +947,25 @@ them, so long as enough of the option is present to be unambiguous.
 (If you prefer, you can flag option arguments with @samp{--} rather
 than @samp{-}, though we illustrate the more usual convention.)
 
+@ifset man
+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.
+@end ifset
+
 @c NOTE: the @cindex entries here use double dashes ON PURPOSE.  This
 @c way, both those who look for -foo and --foo in the index, will find
 @c it.
 
 @table @code
+@ifset man
+@item -help
+@itemx -h
+@cindex @code{--help}
+@cindex @code{-h}
+List all options, with brief explanations.
+@end ifset
+
 @item -symbols @var{file}
 @itemx -s @var{file}
 @cindex @code{--symbols}
@@ -1034,9 +1050,13 @@ This makes startup slower, but makes future operations faster.
 
 @end table
 
+@c man end
+
 @node Mode Options
 @subsection Choosing Modes
 
+@c man begin OPTIONS gdb
+
 You can run @value{GDBN} in various alternative modes---for example, in
 batch mode or quiet mode.
 
@@ -1280,6 +1300,8 @@ important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}).
 
 @end table
 
+@c man end
+
 @node Startup
 @subsection What @value{GDBN} Does During Startup
 @cindex @value{GDBN} startup
@@ -1374,7 +1396,6 @@ 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.
 
-
 @node Quitting GDB
 @section Quitting @value{GDBN}
 @cindex exiting @value{GDBN}
@@ -39837,113 +39858,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

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

[Eli Zaretskii]

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

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

[Pedro Alves]

On 06/10/2014 06:56 PM, Eli Zaretskii wrote:

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

I applied the patch locally, and noticed some things misrendered in the
new man page, like, options are now listed with double quotes instead
of being highlighted.  E.g.:

       "-help"
       "-h"

This one is preexisting, but note "C@t{++}" in:

 "You can use GDB to debug programs written in C, C@t{++}, Fortran and Modula-2."

This sentence seems to be out of place:

 "You can run GDB in various alternative modes---for example, in batch mode or quiet mode."

Not sure, but "---" might be misrendered too.

This incomplete sentence appears, seemingly trying to refer to a chapter
in the manual:

" For further documentation on startup processing, For documentation on how to write command files,"

At this point, I generated a diff of the old/new man pages, in plain text, with:

$ man ./gdb.1 > gdb.1.txt
$ man ./gdb.1.new > gdb.1.new.txt
$ diff -up gdb.1.txt gdb.1.new.txt

I think that's helpful to review this.  The result is below.  Seems there are
other odd things in there, like "GDB/MI INTERFACE" in all caps?


--- gdb.1.txt	2014-06-11 12:27:00.525999781 +0100
+++ gdb.1.new.txt	2014-06-11 12:27:09.823025888 +0100
@@ -83,56 +83,104 @@ DESCRIPTION
        as the "gdb" entry in the "info" program.
 
 OPTIONS
-       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 -se option, and the second, if any, is equivalent to a -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 + rather than -, though we illustrate the more usual convention.)
+       When GDB starts, it reads any arguments other than options as specifying an executable file and core file (or process ID).  This is the same as if the arguments
+       were specified by the -se and -c (or -p) options respectively.  (GDB reads the first argument that does not have an associated option flag as equivalent to the
+       -se option followed by that argument; and the second argument that does not have an associated option flag, if any, as equivalent to the -c/-p option followed
+       by that argument.)  If the second argument begins with a decimal digit, GDB will first attempt to attach to it as a process, and if that fails, attempt to open
+       it as a corefile.  If you have a corefile whose name begins with a digit, you can prevent GDB from treating it as a pid by prefixing it with ./, e.g. ./12345.
+
+       If GDB has not been configured to included core file support, such as for most embedded targets, then it will complain about a second argument and ignore it.
+
+       Many options have both long and short forms; both are shown in the following list.  GDB also recognizes the long forms 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 -- rather than -, 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 -x option is used.
 
-       -help
-       -h  List all options, with brief explanations.
+       "-help"
+       "-h"
+           List all options, with brief explanations.
 
-       -symbols=file
-       -s file
+       "-symbols file"
+       "-s file"
            Read symbol table from file file.
 
-       -write
-           Enable writing into executable and core files.
-
-       -exec=file
-       -e file
+       "-exec file"
+       "-e file"
            Use file file as the executable file to execute when appropriate, and for examining pure data in conjunction with a core dump.
 
-       -se=file
+       "-se file"
            Read symbol table from file file and use it as the executable file.
 
-       -core=file
-       -c file
+       "-core file"
+       "-c file"
            Use file file as a core dump to examine.
 
-       -command=file
-       -x file
-           Execute GDB commands from file file.
+       "-pid number"
+       "-p number"
+           Connect to process ID number, as with the "attach" command.
+
+       "-command file"
+       "-x file"
+           Execute commands from file file.  The contents of this file is evaluated exactly as the "source" command would.
+
+       "-eval-command command"
+       "-ex command"
+           Execute a single GDB command.
+
+           This option may be used multiple times to call multiple commands.  It may also be interleaved with -command as required.
+
+                   gdb -ex 'target sim' -ex 'load' \
+                      -x setbreakpoints -ex 'run' a.out
+
+       "-init-command file"
+       "-ix file"
+           Execute commands from file file before loading the inferior (but after loading gdbinit files).
+
+       "-init-eval-command command"
+       "-iex command"
+           Execute a single GDB command before loading the inferior (but after loading gdbinit files).
+
+       "-directory directory"
+       "-d directory"
+           Add directory to the path to search for source and script files.
 
-       -ex command
-           Execute given GDB command.
+       "-r"
+       "-readnow"
+           Read each symbol file's entire symbol table immediately, rather than the default, which is to read it incrementally as it is needed.  This makes startup
+           slower, but makes future operations faster.
 
-       -directory=directory
-       -d directory
-           Add directory to the path to search for source files.
+       You can run GDB in various alternative modes---for example, in batch mode or quiet mode.
 
-       -nh Do not execute commands from ~/.gdbinit.
+       "-nx"
+       "-n"
+           Do not execute commands found in any initialization file.  There are three init files, loaded in the following order:
 
-       -nx
-       -n  Do not execute commands from any .gdbinit initialization files.
+           "system.gdbinit"
+               This is the system-wide init file.  Its location is specified with the "--with-system-gdbinit" configure option.  It is loaded first when GDB starts,
+               before command line options have been processed.
 
-       -quiet
-       -q  "Quiet".  Do not print the introductory and copyright messages.  These messages are also suppressed in batch mode.
+           "~/.gdbinit"
+               This is the init file in your home directory.  It is loaded next, after system.gdbinit, and before command options have been processed.
 
-       -batch
-           Run in batch mode.  Exit with status 0 after processing all the command files specified with -x (and .gdbinit, if not inhibited).  Exit with nonzero status
-           if an error occurs in executing the GDB commands in the command files.
+           "./.gdbinit"
+               This is the init file in the current directory.  It is loaded last, after command line options other than "-x" and "-ex" have been processed.  Command
+               line options "-x" and "-ex" are processed last, after ./.gdbinit has been loaded.
+
+           For further documentation on startup processing, For documentation on how to write command files,
+
+       "-nh"
+           Do not execute commands found in ~/.gdbinit, the init file in your home directory.
+
+       "-quiet"
+       "-silent"
+       "-q"
+           "Quiet".  Do not print the introductory and copyright messages.  These messages are also suppressed in batch mode.
+
+       "-batch"
+           Run in batch mode.  Exit with status 0 after processing all the command files specified with -x (and all commands from initialization files, if not
+           inhibited with -n).  Exit with nonzero status if an error occurs in executing the GDB commands in the command files.  Batch mode also disables pagination,
+           sets unlimited terminal width and height @pxref{Screen Size}, and acts as if "set confirm off" were in effect.
 
            Batch mode may be useful for running GDB as a filter, for example to download and run a program on another computer; in order to make this more useful, the
            message
@@ -141,21 +189,95 @@ OPTIONS
 
            (which is ordinarily issued whenever a program running under GDB control terminates) is not issued when running in batch mode.
 
-       -cd=directory
+       "-batch-silent"
+           Run in batch mode exactly like -batch, but totally silently.  All GDB output to "stdout" is prevented ("stderr" is unaffected).  This is much quieter than
+           -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 output via GDB, as opposed to writing directly to "stdout", will also be made silent.
+
+       "-return-child-result"
+           The return code from GDB will be the return code from the child process (the process being debugged), with the following exceptions:
+
+           o   GDB exits abnormally.  E.g., due to an incorrect argument or an internal error.  In this case the exit code is the same as it would have been without
+               -return-child-result.
+
+           o   The user quits with an explicit value.  E.g., quit 1.
+
+           o   The child process never runs, or is not allowed to terminate, in which case the exit code will be -1.
+
+           This option is useful in conjunction with -batch or -batch-silent, when GDB is being used as a remote program loader or simulator interface.
+
+       "-nowindows"
+       "-nw"
+           "No windows".  If GDB comes with a graphical user interface (GUI) built in, then this option tells GDB to only use the command-line interface.  If no GUI is
+           available, this option has no effect.
+
+       "-windows"
+       "-w"
+           If GDB includes a GUI, then this option requires it to be used if possible.
+
+       "-cd directory"
            Run GDB using directory as its working directory, instead of the current directory.
 
-       -fullname
-       -f  Emacs sets this option when it runs GDB as a subprocess.  It tells GDB 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 \032 characters, followed by the file
-           name, line number and character position separated by colons, and a newline.  The Emacs-to-GDB interface program uses the two \032 characters as a signal to
-           display the source code for the frame.
+       "-data-directory directory"
+       "-D directory"
+           Run GDB using directory as its data directory.  The data directory is where GDB searches for its auxiliary files.
+
+       "-fullname"
+       "-f"
+           GNU Emacs sets this option when it runs GDB as a subprocess.  It tells GDB 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 your program stops).  This recognizable format looks like two \032 characters, followed by
+           the file name, line number and character position separated by colons, and a newline.  The Emacs-to-GDB interface program uses the two \032 characters as a
+           signal to display the source code for the frame.
+
+       "-annotate level"
+           This option sets the annotation level inside GDB.  Its effect is identical to using set annotate level.  The annotation level controls how much information
+           GDB prints together with its prompt, values of expressions, source lines, and other types of output.  Level 0 is the normal, level 1 is for use when GDB is
+           run as a subprocess of GNU Emacs, level 3 is the maximum annotation suitable for programs that control GDB, and level 2 has been deprecated.
+
+           The annotation mechanism has largely been superseded by GDB/MI.
+
+       "--args"
+           Change interpretation of command line so that arguments following the executable file are passed as command line arguments to the inferior.  This option
+           stops option processing.
 
-       -b bps
+       "-baud bps"
+       "-b bps"
            Set the line speed (baud rate or bits per second) of any serial interface used by GDB for remote debugging.
 
-       -tty=device
+       "-l timeout"
+           Set the timeout (in seconds) of any communication used by GDB for remote debugging.
+
+       "-tty device"
+       "-t device"
            Run using device for your program's standard input and output.
 
+       "-tui"
+           Activate the Text User Interface when starting.  The Text User Interface manages several text windows on the terminal, showing source, assembly, registers
+           and GDB command outputs.  Do not use this option if you run GDB from Emacs.
+
+       "-interpreter interp"
+           Use the interpreter interp for interface with the controlling program or device.  This option is meant to be set by programs which communicate with GDB
+           using it as a back end.
+
+           --interpreter=mi (or --interpreter=mi2) causes GDB to use the GDB/MI INTERFACE included since GDB version 6.0.  The previous GDB/MI interface, included in
+           GDB version 5.3 and selected with --interpreter=mi1, is deprecated.  Earlier GDB/MI interfaces are no longer supported.
+
+       "-write"
+           Open the executable and core files for both reading and writing.  This is equivalent to the set write on command inside GDB.
+
+       "-statistics"
+           This option causes GDB to print statistics about time and memory usage after it completes each command and returns to the prompt.
+
+       "-version"
+           This option causes GDB to print its version number and no-warranty blurb, and exit.
+
+       "-configuration"
+           This option causes GDB to print details about its build-time configuration parameters, and then exit.  These details can be important when reporting GDB
+           bugs.
+
 SEE ALSO
        The full documentation for GDB is maintained as a Texinfo manual.  If the "info" and "gdb" programs and GDB's Texinfo documentation are properly installed at
        your site, the command

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

[Mingjie Xing]

[-- Attachment #1: Type: text/plain, Size: 2722 bytes --]

Hi Pedro, thank you for the careful checking.  See the attachment for
the new patch and the diff result.  Following my comment,

2014-06-11 19:39 GMT+08:00 Pedro Alves <palves@redhat.com>:
> On 06/10/2014 06:56 PM, Eli Zaretskii wrote:
>
>> Thanks.  This looks good to me.  If no one objects, it should go in
>> soon.
>
> I applied the patch locally, and noticed some things misrendered in the
> new man page, like, options are now listed with double quotes instead
> of being highlighted.  E.g.:
>
>        "-help"
>        "-h"

This is because the previous man page uses "@table @env" while the
current Invoke sections uses "@table @code".  I've fixed.

> This one is preexisting, but note "C@t{++}" in:
>
>  "You can use GDB to debug programs written in C, C@t{++}, Fortran and Modula-2."

This seems that texi2pod is unable to handle "@t".  The problem also
occurs for the old man page if you build from the current git.

> This sentence seems to be out of place:
>
>  "You can run GDB in various alternative modes---for example, in batch mode or quiet mode."

OK, I've put it out.

> Not sure, but "---" might be misrendered too.

Hmm, there are many such usage (no space before/afert "--") in gdb.texinfo.

> This incomplete sentence appears, seemingly trying to refer to a chapter
> in the manual:
>
> " For further documentation on startup processing, For documentation on how to write command files,"

Yes, still seems texi2pod's problem, which simply through away the
content for @xref/@pxref.  I've changed ", @xref" to ", see @ref" to
correctly display them in man page.

Note, that current doc uses @xref after a comma, which is incorrect.

> At this point, I generated a diff of the old/new man pages, in plain text, with:
>
> $ man ./gdb.1 > gdb.1.txt
> $ man ./gdb.1.new > gdb.1.new.txt
> $ diff -up gdb.1.txt gdb.1.new.txt
>
> I think that's helpful to review this.  The result is below.  Seems there are
> other odd things in there, like "GDB/MI INTERFACE" in all caps?

Still texi2pod's problem.  It can't handle correctly the nested form
"@dfn{@sc{gdb/mi} interface}".  This can be fix by reorder the process
sequence.  Move

    s/\@sc\{([^\}]*)\}/\U$1/g;

before

    s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g;

But, what if @sc{@dfn{...}}?


doc/ChangeLog,

        * gdb.texinfo (Man Pages): Remove the content of man OPTIONS gdb, add
        a cross reference to 'Invoking GDB'.  To display correctly, change
        'C@t{++}' to 'C++'.
        (Invoking GDB): Share the option sub-sections with man OPTIONS gdb,
        move the uniqe part of man to here.  To display correrctly, change
        ', @xref' to ', see @ref', and change '@table @code' to '@table @env'.

Best regards,
Mingjie

[-- Attachment #2: man.diff --]
[-- Type: text/plain, Size: 11528 bytes --]

27c27
<        You can use GDB to debug programs written in C, C@t{++}, Fortran and Modula-2.
---
>        You can use GDB to debug programs written in C, C++, Fortran and Modula-2.
84,87c84,93
<        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 -se option, and the second, if any, is equivalent to a -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 + rather than -, though
<        we illustrate the more usual convention.)
---
>        When GDB starts, it reads any arguments other than options as specifying an executable file and core file (or process ID).  This is the same as if the arguments were specified by
>        the -se and -c (or -p) options respectively.  (GDB reads the first argument that does not have an associated option flag as equivalent to the -se option followed by that argument;
>        and the second argument that does not have an associated option flag, if any, as equivalent to the -c/-p option followed by that argument.)  If the second argument begins with a
>        decimal digit, GDB will first attempt to attach to it as a process, and if that fails, attempt to open it as a corefile.  If you have a corefile whose name begins with a digit,
>        you can prevent GDB from treating it as a pid by prefixing it with ./, e.g. ./12345.
> 
>        If GDB has not been configured to included core file support, such as for most embedded targets, then it will complain about a second argument and ignore it.
> 
>        Many options have both long and short forms; both are shown in the following list.  GDB also recognizes the long forms 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 -- rather than -, though we illustrate the more usual convention.)
94c100
<        -symbols=file
---
>        -symbols file
98,101c104
<        -write
<            Enable writing into executable and core files.
< 
<        -exec=file
---
>        -exec file
105c108
<        -se=file
---
>        -se file
108c111
<        -core=file
---
>        -core file
112c115,119
<        -command=file
---
>        -pid number
>        -p number
>            Connect to process ID number, as with the "attach" command.
> 
>        -command file
114c121
<            Execute GDB commands from file file.
---
>            Execute commands from file file.  The contents of this file is evaluated exactly as the "source" command would.
115a123
>        -eval-command command
117c125,138
<            Execute given GDB command.
---
>            Execute a single GDB command.
> 
>            This option may be used multiple times to call multiple commands.  It may also be interleaved with -command as required.
> 
>                    gdb -ex 'target sim' -ex 'load' \
>                       -x setbreakpoints -ex 'run' a.out
> 
>        -init-command file
>        -ix file
>            Execute commands from file file before loading the inferior (but after loading gdbinit files).
> 
>        -init-eval-command command
>        -iex command
>            Execute a single GDB command before loading the inferior (but after loading gdbinit files).
119c140
<        -directory=directory
---
>        -directory directory
121c142
<            Add directory to the path to search for source files.
---
>            Add directory to the path to search for source and script files.
123c144,147
<        -nh Do not execute commands from ~/.gdbinit.
---
>        -r
>        -readnow
>            Read each symbol file's entire symbol table immediately, rather than the default, which is to read it incrementally as it is needed.  This makes startup slower, but makes
>            future operations faster.
126c150,165
<        -n  Do not execute commands from any .gdbinit initialization files.
---
>        -n  Do not execute commands found in any initialization file.  There are three init files, loaded in the following order:
> 
>            "system.gdbinit"
>                This is the system-wide init file.  Its location is specified with the "--with-system-gdbinit" configure option.  It is loaded first when GDB starts, before command line
>                options have been processed.
> 
>            "~/.gdbinit"
>                This is the init file in your home directory.  It is loaded next, after system.gdbinit, and before command options have been processed.
> 
>            "./.gdbinit"
>                This is the init file in the current directory.  It is loaded last, after command line options other than "-x" and "-ex" have been processed.  Command line options "-x"
>                and "-ex" are processed last, after ./.gdbinit has been loaded.
> 
>            For further documentation on startup processing, see Startup.  For documentation on how to write command files, see Command Files,,Command Files.
> 
>        -nh Do not execute commands found in ~/.gdbinit, the init file in your home directory.
128a168
>        -silent
132,133c172,174
<            Run in batch mode.  Exit with status 0 after processing all the command files specified with -x (and .gdbinit, if not inhibited).  Exit with nonzero status if an error occurs
<            in executing the GDB commands in the command files.
---
>            Run in batch mode.  Exit with status 0 after processing all the command files specified with -x (and all commands from initialization files, if not inhibited with -n).  Exit
>            with nonzero status if an error occurs in executing the GDB commands in the command files.  Batch mode also disables pagination, sets unlimited terminal width and height, and
>            acts as if "set confirm off" were in effect.
141c182,208
<        -cd=directory
---
>        -batch-silent
>            Run in batch mode exactly like -batch, but totally silently.  All GDB output to "stdout" is prevented ("stderr" is unaffected).  This is much quieter than -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 output via GDB, as opposed to writing directly to "stdout", will also be made silent.
> 
>        -return-child-result
>            The return code from GDB will be the return code from the child process (the process being debugged), with the following exceptions:
> 
>            ·   GDB exits abnormally.  E.g., due to an incorrect argument or an internal error.  In this case the exit code is the same as it would have been without -return-child-result.
> 
>            ·   The user quits with an explicit value.  E.g., quit 1.
> 
>            ·   The child process never runs, or is not allowed to terminate, in which case the exit code will be -1.
> 
>            This option is useful in conjunction with -batch or -batch-silent, when GDB is being used as a remote program loader or simulator interface.
> 
>        -nowindows
>        -nw "No windows".  If GDB comes with a graphical user interface (GUI) built in, then this option tells GDB to only use the command-line interface.  If no GUI is available, this
>            option has no effect.
> 
>        -windows
>        -w  If GDB includes a GUI, then this option requires it to be used if possible.
> 
>        -cd directory
143a211,214
>        -data-directory directory
>        -D directory
>            Run GDB using directory as its data directory.  The data directory is where GDB searches for its auxiliary files.
> 
145,147c216,229
<        -f  Emacs sets this option when it runs GDB as a subprocess.  It tells GDB 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 \032 characters, followed by the file name, line number and character
<            position separated by colons, and a newline.  The Emacs-to-GDB interface program uses the two \032 characters as a signal to display the source code for the frame.
---
>        -f  GNU Emacs sets this option when it runs GDB as a subprocess.  It tells GDB 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 your program stops).  This recognizable format looks like two \032 characters, followed by the file name, line number and
>            character position separated by colons, and a newline.  The Emacs-to-GDB interface program uses the two \032 characters as a signal to display the source code for the frame.
> 
>        -annotate level
>            This option sets the annotation level inside GDB.  Its effect is identical to using set annotate level.  The annotation level controls how much information GDB prints together
>            with its prompt, values of expressions, source lines, and other types of output.  Level 0 is the normal, level 1 is for use when GDB is run as a subprocess of GNU Emacs, level
>            3 is the maximum annotation suitable for programs that control GDB, and level 2 has been deprecated.
> 
>            The annotation mechanism has largely been superseded by GDB/MI.
> 
>        --args
>            Change interpretation of command line so that arguments following the executable file are passed as command line arguments to the inferior.  This option stops option
>            processing.
148a231
>        -baud bps
152c235,239
<        -tty=device
---
>        -l timeout
>            Set the timeout (in seconds) of any communication used by GDB for remote debugging.
> 
>        -tty device
>        -t device
153a241,262
> 
>        -tui
>            Activate the Text User Interface when starting.  The Text User Interface manages several text windows on the terminal, showing source, assembly, registers and GDB command
>            outputs.  Do not use this option if you run GDB from Emacs.
> 
>        -interpreter interp
>            Use the interpreter interp for interface with the controlling program or device.  This option is meant to be set by programs which communicate with GDB using it as a back end.
> 
>            --interpreter=mi (or --interpreter=mi2) causes GDB to use the GDB/MI INTERFACE included since GDB version 6.0.  The previous GDB/MI interface, included in GDB version 5.3 and
>            selected with --interpreter=mi1, is deprecated.  Earlier GDB/MI interfaces are no longer supported.
> 
>        -write
>            Open the executable and core files for both reading and writing.  This is equivalent to the set write on command inside GDB.
> 
>        -statistics
>            This option causes GDB to print statistics about time and memory usage after it completes each command and returns to the prompt.
> 
>        -version
>            This option causes GDB to print its version number and no-warranty blurb, and exit.
> 
>        -configuration
>            This option causes GDB to print details about its build-time configuration parameters, and then exit.  These details can be important when reporting GDB bugs.

[-- Attachment #3: gdb-man.patch --]
[-- Type: text/x-patch, Size: 7506 bytes --]

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a0fb66d..cc46b05 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -921,6 +921,8 @@ in sequential order.  The order makes a difference when the
 @node File Options
 @subsection Choosing Files
 
+@c man begin OPTIONS gdb
+
 When @value{GDBN} starts, it reads any arguments other than options as
 specifying an executable file and core file (or process ID).  This is
 the same as if the arguments were specified by the @samp{-se} and
@@ -945,11 +947,26 @@ them, so long as enough of the option is present to be unambiguous.
 (If you prefer, you can flag option arguments with @samp{--} rather
 than @samp{-}, though we illustrate the more usual convention.)
 
+@ifset man
+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.
+@end ifset
+
 @c NOTE: the @cindex entries here use double dashes ON PURPOSE.  This
 @c way, both those who look for -foo and --foo in the index, will find
 @c it.
 
-@table @code
+@table @env
+
+@ifset man
+@item -help
+@itemx -h
+@cindex @code{--help}
+@cindex @code{-h}
+List all options, with brief explanations.
+@end ifset
+
 @item -symbols @var{file}
 @itemx -s @var{file}
 @cindex @code{--symbols}
@@ -1034,13 +1051,17 @@ This makes startup slower, but makes future operations faster.
 
 @end table
 
+@c man end
+
 @node Mode Options
 @subsection Choosing Modes
 
 You can run @value{GDBN} in various alternative modes---for example, in
 batch mode or quiet mode.
 
-@table @code
+@c man begin OPTIONS gdb
+
+@table @env
 @anchor{-nx}
 @item -nx
 @itemx -n
@@ -1067,9 +1088,9 @@ It is loaded last, after command line options other than @code{-x} and
 @code{-ex} are processed last, after @file{./.gdbinit} has been loaded.
 @end table
 
-For further documentation on startup processing, @xref{Startup}.
+For further documentation on startup processing, see @ref{Startup}.
 For documentation on how to write command files,
-@xref{Command Files,,Command Files}.
+see @ref{Command Files,,Command Files}.
 
 @anchor{-nh}
 @item -nh
@@ -1094,7 +1115,7 @@ command files specified with @samp{-x} (and all commands from
 initialization files, if not inhibited with @samp{-n}).  Exit with
 nonzero status if an error occurs in executing the @value{GDBN} commands
 in the command files.  Batch mode also disables pagination, sets unlimited
-terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm
+terminal width and height (@pxref{Screen Size}), and acts as if @kbd{set confirm
 off} were in effect (@pxref{Messages/Warnings}).
 
 Batch mode may be useful for running @value{GDBN} as a filter, for
@@ -1280,6 +1301,8 @@ important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}).
 
 @end table
 
+@c man end
+
 @node Startup
 @subsection What @value{GDBN} Does During Startup
 @cindex @value{GDBN} startup
@@ -1374,7 +1397,6 @@ 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.
 
-
 @node Quitting GDB
 @section Quitting @value{GDBN}
 @cindex exiting @value{GDBN}
@@ -39753,7 +39775,7 @@ Change things in your program, so you can experiment with correcting the
 effects of one bug and go on to learn about another.
 @end itemize
 
-You can use @value{GDBN} to debug programs written in C, C@t{++}, Fortran and
+You can use @value{GDBN} to debug programs written in C, C++, Fortran and
 Modula-2.
 
 @value{GDBN} is invoked with the shell command @code{gdb}.  Once started, it reads
@@ -39837,113 +39859,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

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

[Pedro Alves]

On 06/12/2014 04:35 AM, Mingjie Xing wrote:
> Hi Pedro, thank you for the careful checking.  See the attachment for
> the new patch and the diff result.  Following my comment,
> 
> 2014-06-11 19:39 GMT+08:00 Pedro Alves <palves@redhat.com>:
>> On 06/10/2014 06:56 PM, Eli Zaretskii wrote:
>>
>>> Thanks.  This looks good to me.  If no one objects, it should go in
>>> soon.
>>
>> I applied the patch locally, and noticed some things misrendered in the
>> new man page, like, options are now listed with double quotes instead
>> of being highlighted.  E.g.:
>>
>>        "-help"
>>        "-h"
> 
> This is because the previous man page uses "@table @env" while the
> current Invoke sections uses "@table @code".  I've fixed.
> 
>> This one is preexisting, but note "C@t{++}" in:
>>
>>  "You can use GDB to debug programs written in C, C@t{++}, Fortran and Modula-2."
> 
> This seems that texi2pod is unable to handle "@t".  The problem also
> occurs for the old man page if you build from the current git.

But then we lose formatting on the info pages, right?

Should we re-define it as a macro under ifset man ?

@ifset man
@macro t{text}
\text\
@end macro
@end ifset

(I don't actually know whether possible.)

> 
>> This sentence seems to be out of place:
>>
>>  "You can run GDB in various alternative modes---for example, in batch mode or quiet mode."
> 
> OK, I've put it out.
> 
>> Not sure, but "---" might be misrendered too.
> 
> Hmm, there are many such usage (no space before/afert "--") in gdb.texinfo.

Those three dashes are rendered as an em dash in texinfo:

 http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Conventions.html

I'd assume the man page should end up with \(em instead of literal ---.

Should we have a macro for this too?

> 
>> This incomplete sentence appears, seemingly trying to refer to a chapter
>> in the manual:
>>
>> " For further documentation on startup processing, For documentation on how to write command files,"
> 
> Yes, still seems texi2pod's problem, which simply through away the
> content for @xref/@pxref.  I've changed ", @xref" to ", see @ref" to
> correctly display them in man page.
> 
> Note, that current doc uses @xref after a comma, which is incorrect.
> 
>> At this point, I generated a diff of the old/new man pages, in plain text, with:
>>
>> $ man ./gdb.1 > gdb.1.txt
>> $ man ./gdb.1.new > gdb.1.new.txt
>> $ diff -up gdb.1.txt gdb.1.new.txt
>>
>> I think that's helpful to review this.  The result is below.  Seems there are
>> other odd things in there, like "GDB/MI INTERFACE" in all caps?
> 
> Still texi2pod's problem.  It can't handle correctly the nested form
> "@dfn{@sc{gdb/mi} interface}".  This can be fix by reorder the process
> sequence.  Move
> 
>     s/\@sc\{([^\}]*)\}/\U$1/g;
> 
> before
> 
>     s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g;
> 
> But, what if @sc{@dfn{...}}?

Hopefully Eli can take a new look.  The new resulting output diff
looks much better to me now.  Thanks for doing this.

-- 
Pedro Alves

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

[Mingjie Xing]

2014-06-23 21:45 GMT+08:00 Pedro Alves <palves@redhat.com>:
>
> Should we re-define it as a macro under ifset man ?
>
> @ifset man
> @macro t{text}
> \text\
> @end macro
> @end ifset
>
> (I don't actually know whether possible.)

This does not work. Add a following command in texi2pod.pl can fix the problem:

    s/\@t\{([^\}]*)\}/$1/g;

> Those three dashes are rendered as an em dash in texinfo:
>
>  http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Conventions.html
>
> I'd assume the man page should end up with \(em instead of literal ---.
>
> Should we have a macro for this too?
>

I think this is also what texi2pod.pl should do.

Best regards,
Mingjie

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

[Eli Zaretskii]

> From: Mingjie Xing <mingjie.xing@gmail.com>
> Date: Tue, 24 Jun 2014 15:08:29 +0800
> Cc: Eli Zaretskii <eliz@gnu.org>, gdb-patches@sourceware.org
> 
> 2014-06-23 21:45 GMT+08:00 Pedro Alves <palves@redhat.com>:
> >
> > Should we re-define it as a macro under ifset man ?
> >
> > @ifset man
> > @macro t{text}
> > \text\
> > @end macro
> > @end ifset
> >
> > (I don't actually know whether possible.)
> 
> This does not work.

What exactly doesn't work, and how?

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

[Mingjie Xing]

2014-06-24 23:55 GMT+08:00 Eli Zaretskii <eliz@gnu.org>:
>> From: Mingjie Xing <mingjie.xing@gmail.com>
>> Date: Tue, 24 Jun 2014 15:08:29 +0800
>> Cc: Eli Zaretskii <eliz@gnu.org>, gdb-patches@sourceware.org
>>
>> 2014-06-23 21:45 GMT+08:00 Pedro Alves <palves@redhat.com>:
>> >
>> > Should we re-define it as a macro under ifset man ?
>> >
>> > @ifset man
>> > @macro t{text}
>> > \text\
>> > @end macro
>> > @end ifset
>> >
>> > (I don't actually know whether possible.)
>>
>> This does not work.
>
> What exactly doesn't work, and how?

The man pages are generated by texi2pod.pl which doesn't care about
texinfo macros.  So with the above macro re-definition, "C@t{++}"
would still be misrendered.

So what I suggest is to retain "C@t{++}" in gdb.texinfo, and add a
substitution "s/\@t\{([^\}]*)\}/$1/g;" in texi2pod.pl. Thus the format
will not be lost in info pages.

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

[Mingjie Xing]

[-- Attachment #1: Type: text/plain, Size: 717 bytes --]

I'd like to put an updated patch for both gdb.texinfo and texi2pod.pl,
plus the new comparing result.

etc/ChangeLog:

        * texi2pod.pl (postprocess): Move command process for '@sc' to the
        front of '@dfn'.  Add a new command process for '@t{...}', just print
        the content.

gdb/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 here.  To display correrctly in man
page,
        change '@xref' after a comma to 'see @ref', and change '@table
@code'
        to '@table @env'.

Best regards,
Mingjie

[-- Attachment #2: man.diff --]
[-- Type: text/plain, Size: 11629 bytes --]

27c27
<        You can use GDB to debug programs written in C, C@t{++}, Fortran and Modula-2.
---
>        You can use GDB to debug programs written in C, C++, Fortran and Modula-2.
84,87c84,93
<        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 -se option, and the second, if any, is equivalent to a -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 + rather than -, though
<        we illustrate the more usual convention.)
---
>        When GDB starts, it reads any arguments other than options as specifying an executable file and core file (or process ID).  This is the same as if the arguments were specified by
>        the -se and -c (or -p) options respectively.  (GDB reads the first argument that does not have an associated option flag as equivalent to the -se option followed by that argument;
>        and the second argument that does not have an associated option flag, if any, as equivalent to the -c/-p option followed by that argument.)  If the second argument begins with a
>        decimal digit, GDB will first attempt to attach to it as a process, and if that fails, attempt to open it as a corefile.  If you have a corefile whose name begins with a digit,
>        you can prevent GDB from treating it as a pid by prefixing it with ./, e.g. ./12345.
> 
>        If GDB has not been configured to included core file support, such as for most embedded targets, then it will complain about a second argument and ignore it.
> 
>        Many options have both long and short forms; both are shown in the following list.  GDB also recognizes the long forms 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 -- rather than -, though we illustrate the more usual convention.)
94c100
<        -symbols=file
---
>        -symbols file
98,101c104
<        -write
<            Enable writing into executable and core files.
< 
<        -exec=file
---
>        -exec file
105c108
<        -se=file
---
>        -se file
108c111
<        -core=file
---
>        -core file
112c115,119
<        -command=file
---
>        -pid number
>        -p number
>            Connect to process ID number, as with the "attach" command.
> 
>        -command file
114c121
<            Execute GDB commands from file file.
---
>            Execute commands from file file.  The contents of this file is evaluated exactly as the "source" command would.
115a123
>        -eval-command command
117c125,138
<            Execute given GDB command.
---
>            Execute a single GDB command.
> 
>            This option may be used multiple times to call multiple commands.  It may also be interleaved with -command as required.
> 
>                    gdb -ex 'target sim' -ex 'load' \
>                       -x setbreakpoints -ex 'run' a.out
> 
>        -init-command file
>        -ix file
>            Execute commands from file file before loading the inferior (but after loading gdbinit files).
> 
>        -init-eval-command command
>        -iex command
>            Execute a single GDB command before loading the inferior (but after loading gdbinit files).
119c140
<        -directory=directory
---
>        -directory directory
121c142
<            Add directory to the path to search for source files.
---
>            Add directory to the path to search for source and script files.
123c144,149
<        -nh Do not execute commands from ~/.gdbinit.
---
>        -r
>        -readnow
>            Read each symbol file's entire symbol table immediately, rather than the default, which is to read it incrementally as it is needed.  This makes startup slower, but makes
>            future operations faster.
> 
>        You can run GDB in various alternative modes---for example, in batch mode or quiet mode.
126c152,167
<        -n  Do not execute commands from any .gdbinit initialization files.
---
>        -n  Do not execute commands found in any initialization file.  There are three init files, loaded in the following order:
> 
>            "system.gdbinit"
>                This is the system-wide init file.  Its location is specified with the "--with-system-gdbinit" configure option.  It is loaded first when GDB starts, before command line
>                options have been processed.
> 
>            "~/.gdbinit"
>                This is the init file in your home directory.  It is loaded next, after system.gdbinit, and before command options have been processed.
> 
>            "./.gdbinit"
>                This is the init file in the current directory.  It is loaded last, after command line options other than "-x" and "-ex" have been processed.  Command line options "-x"
>                and "-ex" are processed last, after ./.gdbinit has been loaded.
> 
>            For further documentation on startup processing, see Startup.  For documentation on how to write command files, see Command Files,,Command Files.
> 
>        -nh Do not execute commands found in ~/.gdbinit, the init file in your home directory.
128a170
>        -silent
132,133c174,176
<            Run in batch mode.  Exit with status 0 after processing all the command files specified with -x (and .gdbinit, if not inhibited).  Exit with nonzero status if an error occurs
<            in executing the GDB commands in the command files.
---
>            Run in batch mode.  Exit with status 0 after processing all the command files specified with -x (and all commands from initialization files, if not inhibited with -n).  Exit
>            with nonzero status if an error occurs in executing the GDB commands in the command files.  Batch mode also disables pagination, sets unlimited terminal width and height, and
>            acts as if "set confirm off" were in effect.
141c184,210
<        -cd=directory
---
>        -batch-silent
>            Run in batch mode exactly like -batch, but totally silently.  All GDB output to "stdout" is prevented ("stderr" is unaffected).  This is much quieter than -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 output via GDB, as opposed to writing directly to "stdout", will also be made silent.
> 
>        -return-child-result
>            The return code from GDB will be the return code from the child process (the process being debugged), with the following exceptions:
> 
>            ·   GDB exits abnormally.  E.g., due to an incorrect argument or an internal error.  In this case the exit code is the same as it would have been without -return-child-result.
> 
>            ·   The user quits with an explicit value.  E.g., quit 1.
> 
>            ·   The child process never runs, or is not allowed to terminate, in which case the exit code will be -1.
> 
>            This option is useful in conjunction with -batch or -batch-silent, when GDB is being used as a remote program loader or simulator interface.
> 
>        -nowindows
>        -nw "No windows".  If GDB comes with a graphical user interface (GUI) built in, then this option tells GDB to only use the command-line interface.  If no GUI is available, this
>            option has no effect.
> 
>        -windows
>        -w  If GDB includes a GUI, then this option requires it to be used if possible.
> 
>        -cd directory
143a213,216
>        -data-directory directory
>        -D directory
>            Run GDB using directory as its data directory.  The data directory is where GDB searches for its auxiliary files.
> 
145,147c218,231
<        -f  Emacs sets this option when it runs GDB as a subprocess.  It tells GDB 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 \032 characters, followed by the file name, line number and character
<            position separated by colons, and a newline.  The Emacs-to-GDB interface program uses the two \032 characters as a signal to display the source code for the frame.
---
>        -f  GNU Emacs sets this option when it runs GDB as a subprocess.  It tells GDB 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 your program stops).  This recognizable format looks like two \032 characters, followed by the file name, line number and
>            character position separated by colons, and a newline.  The Emacs-to-GDB interface program uses the two \032 characters as a signal to display the source code for the frame.
> 
>        -annotate level
>            This option sets the annotation level inside GDB.  Its effect is identical to using set annotate level.  The annotation level controls how much information GDB prints together
>            with its prompt, values of expressions, source lines, and other types of output.  Level 0 is the normal, level 1 is for use when GDB is run as a subprocess of GNU Emacs, level
>            3 is the maximum annotation suitable for programs that control GDB, and level 2 has been deprecated.
> 
>            The annotation mechanism has largely been superseded by GDB/MI.
> 
>        --args
>            Change interpretation of command line so that arguments following the executable file are passed as command line arguments to the inferior.  This option stops option
>            processing.
148a233
>        -baud bps
152c237,241
<        -tty=device
---
>        -l timeout
>            Set the timeout (in seconds) of any communication used by GDB for remote debugging.
> 
>        -tty device
>        -t device
153a243,264
> 
>        -tui
>            Activate the Text User Interface when starting.  The Text User Interface manages several text windows on the terminal, showing source, assembly, registers and GDB command
>            outputs.  Do not use this option if you run GDB from Emacs.
> 
>        -interpreter interp
>            Use the interpreter interp for interface with the controlling program or device.  This option is meant to be set by programs which communicate with GDB using it as a back end.
> 
>            --interpreter=mi (or --interpreter=mi2) causes GDB to use the GDB/MI interface included since GDB version 6.0.  The previous GDB/MI interface, included in GDB version 5.3 and
>            selected with --interpreter=mi1, is deprecated.  Earlier GDB/MI interfaces are no longer supported.
> 
>        -write
>            Open the executable and core files for both reading and writing.  This is equivalent to the set write on command inside GDB.
> 
>        -statistics
>            This option causes GDB to print statistics about time and memory usage after it completes each command and returns to the prompt.
> 
>        -version
>            This option causes GDB to print its version number and no-warranty blurb, and exit.
> 
>        -configuration
>            This option causes GDB to print details about its build-time configuration parameters, and then exit.  These details can be important when reporting GDB bugs.

[-- Attachment #3: gdb-man.patch --]
[-- Type: text/x-patch, Size: 7820 bytes --]

diff --git a/etc/texi2pod.pl b/etc/texi2pod.pl
index cd0ffd9..4337469 100644
--- a/etc/texi2pod.pl
+++ b/etc/texi2pod.pl
@@ -374,13 +374,14 @@ sub postprocess
     # Formatting commands.
     # Temporary escape for @r.
     s/\@r\{([^\}]*)\}/R<$1>/g;
+    s/\@sc\{([^\}]*)\}/\U$1/g;
     s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g;
     s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g;
     s/\@(?:gccoptlist|samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<$1>/g;
-    s/\@sc\{([^\}]*)\}/\U$1/g;
     s/\@file\{([^\}]*)\}/F<$1>/g;
     s/\@w\{([^\}]*)\}/S<$1>/g;
     s/\@(?:dmn|math)\{([^\}]*)\}/$1/g;
+    s/\@t\{([^\}]*)\}/$1/g;
 
     # keep references of the form @ref{...}, print them bold
     s/\@(?:ref)\{([^\}]*)\}/B<$1>/g;
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a0fb66d..3459996 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -921,6 +921,8 @@ in sequential order.  The order makes a difference when the
 @node File Options
 @subsection Choosing Files
 
+@c man begin OPTIONS gdb
+
 When @value{GDBN} starts, it reads any arguments other than options as
 specifying an executable file and core file (or process ID).  This is
 the same as if the arguments were specified by the @samp{-se} and
@@ -945,11 +947,26 @@ them, so long as enough of the option is present to be unambiguous.
 (If you prefer, you can flag option arguments with @samp{--} rather
 than @samp{-}, though we illustrate the more usual convention.)
 
+@ifset man
+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.
+@end ifset
+
 @c NOTE: the @cindex entries here use double dashes ON PURPOSE.  This
 @c way, both those who look for -foo and --foo in the index, will find
 @c it.
 
-@table @code
+@table @env
+
+@ifset man
+@item -help
+@itemx -h
+@cindex @code{--help}
+@cindex @code{-h}
+List all options, with brief explanations.
+@end ifset
+
 @item -symbols @var{file}
 @itemx -s @var{file}
 @cindex @code{--symbols}
@@ -1034,13 +1051,17 @@ This makes startup slower, but makes future operations faster.
 
 @end table
 
+@c man end
+
 @node Mode Options
 @subsection Choosing Modes
 
+@c man begin OPTIONS gdb
+
 You can run @value{GDBN} in various alternative modes---for example, in
 batch mode or quiet mode.
 
-@table @code
+@table @env
 @anchor{-nx}
 @item -nx
 @itemx -n
@@ -1067,9 +1088,9 @@ It is loaded last, after command line options other than @code{-x} and
 @code{-ex} are processed last, after @file{./.gdbinit} has been loaded.
 @end table
 
-For further documentation on startup processing, @xref{Startup}.
+For further documentation on startup processing, see @ref{Startup}.
 For documentation on how to write command files,
-@xref{Command Files,,Command Files}.
+see @ref{Command Files,,Command Files}.
 
 @anchor{-nh}
 @item -nh
@@ -1094,7 +1115,7 @@ command files specified with @samp{-x} (and all commands from
 initialization files, if not inhibited with @samp{-n}).  Exit with
 nonzero status if an error occurs in executing the @value{GDBN} commands
 in the command files.  Batch mode also disables pagination, sets unlimited
-terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm
+terminal width and height (@pxref{Screen Size}), and acts as if @kbd{set confirm
 off} were in effect (@pxref{Messages/Warnings}).
 
 Batch mode may be useful for running @value{GDBN} as a filter, for
@@ -1280,6 +1301,8 @@ important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}).
 
 @end table
 
+@c man end
+
 @node Startup
 @subsection What @value{GDBN} Does During Startup
 @cindex @value{GDBN} startup
@@ -1374,7 +1397,6 @@ 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.
 
-
 @node Quitting GDB
 @section Quitting @value{GDBN}
 @cindex exiting @value{GDBN}
@@ -39837,113 +39859,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

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

[Mingjie Xing]

Ping.

2014-06-26 17:34 GMT+08:00 Mingjie Xing <mingjie.xing@gmail.com>:
> I'd like to put an updated patch for both gdb.texinfo and texi2pod.pl,
> plus the new comparing result.
>
> etc/ChangeLog:
>
>         * texi2pod.pl (postprocess): Move command process for '@sc' to the
>         front of '@dfn'.  Add a new command process for '@t{...}', just print
>         the content.
>
> gdb/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 here.  To display correrctly in man
> page,
>         change '@xref' after a comma to 'see @ref', and change '@table
> @code'
>         to '@table @env'.
>
> Best regards,
> Mingjie

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

[Joel Brobecker]

> Ping.
> 
> 2014-06-26 17:34 GMT+08:00 Mingjie Xing <mingjie.xing@gmail.com>:
> > I'd like to put an updated patch for both gdb.texinfo and texi2pod.pl,
> > plus the new comparing result.
> >
> > etc/ChangeLog:
> >
> >         * texi2pod.pl (postprocess): Move command process for '@sc' to the
> >         front of '@dfn'.  Add a new command process for '@t{...}', just print
> >         the content.
> >
> > gdb/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 here.  To display correrctly in man
> > page,
> >         change '@xref' after a comma to 'see @ref', and change '@table
> > @code'
> >         to '@table @env'.

This is a documentation patch, so best to attract the documentation
maintainer's attention by adding something like "DOCO" in the email
subject.

Also, I think I saw that your patch was missing context info (ie,
straight diff), making it really hard to review. My suggestion is
to work straight off the git repository, to commit the change,
and then to email the patch. "git send-email" is very handy in
that regard.

-- 
Joel

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

[Eli Zaretskii]

> Date: Mon, 7 Jul 2014 07:18:43 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, Pedro Alves <palves@redhat.com>,
> 	gdb-patches@sourceware.org
> 
> > Ping.
> > 
> > 2014-06-26 17:34 GMT+08:00 Mingjie Xing <mingjie.xing@gmail.com>:
> > > I'd like to put an updated patch for both gdb.texinfo and texi2pod.pl,
> > > plus the new comparing result.
> > >
> > > etc/ChangeLog:
> > >
> > >         * texi2pod.pl (postprocess): Move command process for '@sc' to the
> > >         front of '@dfn'.  Add a new command process for '@t{...}', just print
> > >         the content.
> > >
> > > gdb/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 here.  To display correrctly in man
> > > page,
> > >         change '@xref' after a comma to 'see @ref', and change '@table
> > > @code'
> > >         to '@table @env'.
> 
> This is a documentation patch, so best to attract the documentation
> maintainer's attention by adding something like "DOCO" in the email
> subject.

Frankly, I just don't know what to do with this patch.

I don't know enough Perl to judge the texi2pod.pl patch, and don't
intend to learn Perl just for that purpose.  On top of that, this
whole "produce man pages from Texinfo" business was sold to us on the
assumption that "it makes maintenance simpler" (see
https://sourceware.org/ml/gdb-patches/2013-02/msg00290.html and the
discussions around it).  To me this means that we put a bunch of
telltale markers into the Texinfo files, add a few Makefile rules, and
promptly forget everything we knew about that.

But now it sounds like this arrangement is not simple at all, that we
need non-trivial changes to follow (which will probably stump someone
at some point, and perhaps even be changed and break the man-page
generation), we need to maintain texi2pod.pl, and whatnot else.  And
I'm the person who needs to be responsible for it.

So I'm beginning to doubt that this is for the better.

Thoughts?

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

[Joel Brobecker]

> So I'm beginning to doubt that this is for the better.
> 
> Thoughts?

I would follow your recommendation, here. If it's simpler to update
our procedures, and occasionally have to duplicate a bit our doco
work for the man page, I'd be OK with that.

-- 
Joel

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

[Pedro Alves]

On 07/07/2014 04:26 PM, Eli Zaretskii wrote:

> Frankly, I just don't know what to do with this patch.
> 
> I don't know enough Perl to judge the texi2pod.pl patch, and don't
> intend to learn Perl just for that purpose.

I didn't know about texi2pod.pl until Mingjie's patch, nor did I
know we had it in the tree under etc/.  Looking around, AFAICS, the
file is maintained in GCC, as indicated in its header:
"# This file is part of GCC.".  'git log' also shows entries like:

            Move from gcc:
...
        * texi2pod.pl: Import latest version from GCC.

GCC's version has a few changes from 2010 that our copy doesn't have.

I think we should start by updating our copy from gcc/upstream.

And then the etc/ patch should be sent to gcc-patches@ (CCing gdb-patches@).

Mingjie, would you like to champion that?

>  On top of that, this
> whole "produce man pages from Texinfo" business was sold to us on the
> assumption that "it makes maintenance simpler" (see
> https://sourceware.org/ml/gdb-patches/2013-02/msg00290.html and the
> discussions around it).  To me this means that we put a bunch of
> telltale markers into the Texinfo files, add a few Makefile rules, and
> promptly forget everything we knew about that.
> 
> But now it sounds like this arrangement is not simple at all, that we
> need non-trivial changes to follow (which will probably stump someone
> at some point, and perhaps even be changed and break the man-page
> generation), we need to maintain texi2pod.pl, and whatnot else.

I found some documention on texi2pod.pl here:

 https://gcc.gnu.org/onlinedocs/gccint/Man-Page-Generation.html

Sounds like we actually want '@table @gcctabopt'.

> So I'm beginning to doubt that this is for the better.

I think the benefits once this is in place outweigh the hurdle we're
going through.  I'd rather have a synced man page with the occasional
odd formatting (that gets fixed eventually) than having to keep
the two texts in sync manually.

-- 
Pedro Alves

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

[Eli Zaretskii]

> Date: Tue, 08 Jul 2014 10:47:37 +0100
> From: Pedro Alves <palves@redhat.com>
> CC: mingjie.xing@gmail.com, gdb-patches@sourceware.org
> 
> >  On top of that, this
> > whole "produce man pages from Texinfo" business was sold to us on the
> > assumption that "it makes maintenance simpler" (see
> > https://sourceware.org/ml/gdb-patches/2013-02/msg00290.html and the
> > discussions around it).  To me this means that we put a bunch of
> > telltale markers into the Texinfo files, add a few Makefile rules, and
> > promptly forget everything we knew about that.
> > 
> > But now it sounds like this arrangement is not simple at all, that we
> > need non-trivial changes to follow (which will probably stump someone
> > at some point, and perhaps even be changed and break the man-page
> > generation), we need to maintain texi2pod.pl, and whatnot else.
> 
> I found some documention on texi2pod.pl here:
> 
>  https://gcc.gnu.org/onlinedocs/gccint/Man-Page-Generation.html
> 
> Sounds like we actually want '@table @gcctabopt'.
> 
> > So I'm beginning to doubt that this is for the better.
> 
> I think the benefits once this is in place outweigh the hurdle we're
> going through.  I'd rather have a synced man page with the occasional
> odd formatting (that gets fixed eventually) than having to keep
> the two texts in sync manually.

In that case, if everyone else is happy with the patch, please approve
it, and let's see what happens next.