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

Pedro Alves
2014-06-11T11:39:48Z

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