Message ID | CADNgcEzJeWQh-rt57hVsyZnq7qVfR2dJCV9X5tu4jDyu=mNFyw@mail.gmail.com |
---|---|
State | New |
Headers | show |
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
> 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.
> 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?
> 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.
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.
> 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.
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