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

[Pedro Alves <palves at redhat dot 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 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