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

[Mingjie Xing <mingjie dot xing at gmail dot com>]

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: man.diff
Description: Text document

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