forked from Imagelibrary/binutils-gdb
590042fc45
With this patch, the help docs now respect 2 invariants: * The first line of a command help is terminated by a '.' character. * The last character of a command help is not a newline character. Note that the changes for the last invariant were done by Tom, as part of : [PATCH] Remove trailing newlines from help text https://sourceware.org/ml/gdb-patches/2019-06/msg00050.html but some occurrences have been re-introduced since then. Some help docs had to be rephrased/restructured to respect the above invariants. Before this patch, print_doc_line was printing the first line of a command help documentation, but stopping at the first '.' or ',' character. This was giving inconsistent results : * The first line of command helps was sometimes '.' terminated, sometimes not. * The first line of command helps was not always designed to be readable/understandable/unambiguous when stopping at the first '.' or ',' character. This e.g. created the following inconsistencies/problems: < catch exception -- Catch Ada exceptions < catch handlers -- Catch Ada exceptions < catch syscall -- Catch system calls by their names < down-silently -- Same as the `down' command while the new help is: > catch exception -- Catch Ada exceptions, when raised. > catch handlers -- Catch Ada exceptions, when handled. > catch syscall -- Catch system calls by their names, groups and/or numbers. > down-silently -- Same as the `down' command, but does not print anything. Also, the command help doc should not be terminated by a newline character, but this was not respected by all commands. The cli-option -OPT framework re-introduced some occurences. So, the -OPT build help framework was changed to not output newlines at the end of %OPTIONS% replacement. This patch changes the help documentations to ensure the 2 invariants given above. It implied to slightly rephrase or restructure some help docs. Based on the above invariants, print_doc_line (called by 'apropos' and 'help' commands to print the first line of a command help) now outputs the full first line of a command help. This all results in a lot of small changes in the produced help docs. There are less code changes than changes in the help docs, as a lot of docs are produced by some code (e.g. the remote packet usage settings). gdb/ChangeLog 2019-08-07 Philippe Waroquiers <philippe.waroquiers@skynet.be> * cli/cli-decode.h (print_doc_line): Add for_value_prefix argument. * cli/cli-decode.c (print_doc_line): Likewise. It now prints the full first line, except when FOR_VALUE_PREFIX. In this case, the trailing '.' is not output, and the first character is uppercased. (print_help_for_command): Update call to print_doc_line. (print_doc_of_command): Likewise. * cli/cli-setshow.c (deprecated_show_value_hack): Likewise. * cli/cli-option.c (append_indented_doc): Do not append newline. (build_help_option): Append newline after first appended_indented_doc only if a second call is done. (build_help): Append 2 new lines before each option, except the first one. * compile/compile.c (_initialize_compile): Add new lines after %OPTIONS%, when not at the end of the help. Change help doc or code producing the help doc to respect the invariants. * maint-test-options.c (_initialize_maint_test_options): Likewise. Also removed the new line after 'Options:', as all other commands do not put an empty line between 'Options:' and the first option. * printcmd.c (_initialize_printcmd): Likewise. * stack.c (_initialize_stack): Likewise. * interps.c (interpreter_exec_cmd): Fix "Usage:" line that was incorrectly telling COMMAND is optional. * ada-lang.c (_initialize_ada_language): Change help doc or code producing the help doc to respect the invariants. * ada-tasks.c (_initialize_ada_tasks): Likewise. * breakpoint.c (_initialize_breakpoint): Likewise. * cli/cli-cmds.c (_initialize_cli_cmds): Likewise. * cli/cli-logging.c (_initialize_cli_logging): Likewise. * cli/cli-setshow.c (_initialize_cli_setshow): Likewise. * cli/cli-style.c (cli_style_option::add_setshow_commands, _initialize_cli_style): Likewise. * corelow.c (core_target_info): Likewise. * dwarf-index-cache.c (_initialize_index_cache): Likewise. * dwarf2read.c (_initialize_dwarf2_read): Likewise. * filesystem.c (_initialize_filesystem): Likewise. * frame.c (_initialize_frame): Likewise. * gnu-nat.c (add_task_commands): Likewise. * infcall.c (_initialize_infcall): Likewise. * infcmd.c (_initialize_infcmd): Likewise. * interps.c (_initialize_interpreter): Likewise. * language.c (_initialize_language): Likewise. * linux-fork.c (_initialize_linux_fork): Likewise. * maint-test-settings.c (_initialize_maint_test_settings): Likewise. * maint.c (_initialize_maint_cmds): Likewise. * memattr.c (_initialize_mem): Likewise. * printcmd.c (_initialize_printcmd): Likewise. * python/lib/gdb/function/strfns.py (_MemEq, _StrLen, _StrEq, _RegEx): Likewise. * ravenscar-thread.c (_initialize_ravenscar): Likewise. * record-btrace.c (_initialize_record_btrace): Likewise. * record-full.c (_initialize_record_full): Likewise. * record.c (_initialize_record): Likewise. * regcache-dump.c (_initialize_regcache_dump): Likewise. * regcache.c (_initialize_regcache): Likewise. * remote.c (add_packet_config_cmd, init_remote_threadtests, _initialize_remote): Likewise. * ser-tcp.c (_initialize_ser_tcp): Likewise. * serial.c (_initialize_serial): Likewise. * skip.c (_initialize_step_skip): Likewise. * source.c (_initialize_source): Likewise. * stack.c (_initialize_stack): Likewise. * symfile.c (_initialize_symfile): Likewise. * symtab.c (_initialize_symtab): Likewise. * target-descriptions.c (_initialize_target_descriptions): Likewise. * top.c (init_main): Likewise. * tracefile-tfile.c (tfile_target_info): Likewise. * tracepoint.c (_initialize_tracepoint): Likewise. * tui/tui-win.c (_initialize_tui_win): Likewise. * utils.c (add_internal_problem_command): Likewise. * valprint.c (value_print_option_defs): Likewise. gdb/testsuite/ChangeLog 2019-08-07 Philippe Waroquiers <philippe.waroquiers@skynet.be> * gdb.base/style.exp: Update tests for help doc new invariants. * gdb.base/help.exp: Likewise.
131 lines
6.3 KiB
Plaintext
131 lines
6.3 KiB
Plaintext
# Copyright 1988-2019 Free Software Foundation, Inc.
|
|
|
|
# This program is free software; you can redistribute it and/or modify
|
|
# it under the terms of the GNU General Public License as published by
|
|
# the Free Software Foundation; either version 3 of the License, or
|
|
# (at your option) any later version.
|
|
#
|
|
# This program is distributed in the hope that it will be useful,
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
# GNU General Public License for more details.
|
|
#
|
|
# You should have received a copy of the GNU General Public License
|
|
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
# This file was written by Rob Savoye. (rob@cygnus.com)
|
|
|
|
# Test basic help functionality.
|
|
# This is not intended to test the help text of every command,
|
|
# or even more than a few commands - too much of a maintenance burden.
|
|
|
|
gdb_start
|
|
|
|
# disable pagination
|
|
gdb_test_no_output "set height 0" "disable pagination"
|
|
|
|
# Test all the help classes.
|
|
test_class_help "aliases" {"Aliases of other commands\.\[\r\n\]+"}
|
|
test_class_help "breakpoints" {
|
|
"Making program stop at certain points\.\[\r\n\]+"
|
|
}
|
|
with_read1_timeout_factor 10 {
|
|
test_class_help "data" {"Examining data\.\[\r\n\]+"}
|
|
test_class_help "files" {"Specifying and examining files\.\[\r\n\]+"}
|
|
test_class_help "internals" {
|
|
"Maintenance commands\.\[\r\n\]+"
|
|
"Some gdb commands are provided just for use by gdb maintainers\.\[\r\n\]+"
|
|
"These commands are subject to frequent change, and may not be as\[\r\n\]+"
|
|
"well documented as user commands\.\[\r\n\]+"
|
|
}
|
|
}
|
|
test_class_help "obscure" {"Obscure features\.\[\r\n\]+"}
|
|
test_class_help "running" {"Running the program\.\[\r\n\]+"}
|
|
test_class_help "stack" {
|
|
"Examining the stack\..*\[\r\n\]+"
|
|
"When the program being debugged stops, gdb selects the innermost frame\.\[\r\n\]+"
|
|
"The commands below can be used to select other frames by number or address\.\[\r\n\]+"
|
|
}
|
|
with_read1_timeout_factor 10 {
|
|
test_class_help "status" {
|
|
"Status inquiries\.\[\r\n\]+"
|
|
}
|
|
test_class_help "support" {"Support facilities\.\[\r\n\]+"}
|
|
test_class_help "tracepoints" {
|
|
"Tracing of program execution without stopping the program\.\[\r\n\]+"
|
|
}
|
|
}
|
|
|
|
with_read1_timeout_factor 10 {
|
|
test_user_defined_class_help
|
|
|
|
# Test help of an abbreviated command. "break" is picked at random.
|
|
set help_breakpoint_text "Set breakpoint at specified location\..*"
|
|
# test help breakpoint "b" abbreviation
|
|
gdb_test "help b" $help_breakpoint_text "help breakpoint \"b\" abbreviation"
|
|
# test help breakpoint "br" abbreviation
|
|
gdb_test "help br" $help_breakpoint_text "help breakpoint \"br\" abbreviation"
|
|
# test help breakpoint "bre" abbreviation
|
|
gdb_test "help bre" $help_breakpoint_text "help breakpoint \"bre\" abbreviation"
|
|
# test help breakpoint "brea" abbreviation
|
|
}
|
|
gdb_test "help brea" $help_breakpoint_text "help breakpoint \"brea\" abbreviation"
|
|
# test help breakpoint "break" abbreviation
|
|
gdb_test "help break" $help_breakpoint_text "help breakpoint \"break\" abbreviation"
|
|
|
|
# Test help of an aliased command. "bt" is picked at random.
|
|
set help_backtrace_text "Print backtrace of all stack frames, or innermost COUNT frames\..*"
|
|
# test help backtrace "bt" abbreviation
|
|
gdb_test "help bt" $help_backtrace_text "help backtrace \"bt\" abbreviation"
|
|
# test help backtrace
|
|
gdb_test "help backtrace" $help_backtrace_text "help backtrace"
|
|
|
|
# test help commands
|
|
gdb_test "help commands" "Set commands to be executed when the given breakpoints are hit\.\[\r\n\]+Give a space-separated breakpoint list as argument after \"commands\"\.\[\r\n\]+A list element can be a breakpoint number \\(e.g. `5'\\) or a range of numbers\[\r\n\]+\\(e.g. `5-7'\\)\.\[\r\n\]+With no argument, the targeted breakpoint is the last one set\.\[\r\n\]+The commands themselves follow starting on the next line\.\[\r\n\]+Type a line containing \"end\" to indicate the end of them\.\[\r\n\]+Give \"silent\" as the first line to make the breakpoint silent;\[\r\n\]+then no output is printed when it is hit, except what the commands print\." "help commands"
|
|
|
|
# Test a prefix command. "delete" is picked at random.
|
|
# test help delete "d" abbreviation
|
|
set expected_help_delete {
|
|
"Delete all or some breakpoints\.\[\r\n\]+"
|
|
"Usage: delete \\\[BREAKPOINTNUM\\\]...\[\r\n\]+"
|
|
"Arguments are breakpoint numbers with spaces in between\.\[\r\n\]+"
|
|
"To delete all breakpoints, give no argument\.\[\r\n\]+"
|
|
"Also a prefix command for deletion of other GDB objects\.\[\r\n\]+"
|
|
}
|
|
test_prefix_command_help {"d" "delete"} $expected_help_delete "help delete \"d\" abbreviation"
|
|
# test help delete
|
|
test_prefix_command_help "delete" $expected_help_delete
|
|
|
|
# Make sure help for help itself is present.
|
|
# test help help "h" abbreviation
|
|
gdb_test "help h" "Print list of commands\." "help help \"h\" abbreviation"
|
|
# test help help
|
|
gdb_test "help help" "Print list of commands\." "help help"
|
|
|
|
# The startup banner refers to "show copying" and "show warranty",
|
|
# might as well test for them.
|
|
# test help info copying
|
|
gdb_test "help show copying" "Conditions for redistributing copies of GDB\." \
|
|
"help show copying"
|
|
# test help info warranty
|
|
gdb_test "help show warranty" "Various kinds of warranty you do not have\." \
|
|
"help show warranty"
|
|
|
|
# Test a few other random "help show" commands.
|
|
# test help show commands
|
|
gdb_test "help show commands" "Show the history of commands you typed\.\[\r\n\]+You can supply a command number to start with, or a `\[+\]' to start after\[\r\n\]+the previous command number shown\." "help show commands"
|
|
# test help show confirm
|
|
gdb_test "help show confirm" "Show whether to confirm potentially dangerous operations\." "help show confirm"
|
|
|
|
# test help info bogus-gdb-command
|
|
gdb_test "help info bogus-gdb-command" "Undefined info command: \"bogus-gdb-command\"\. Try \"help info\"\." "help info bogus-gdb-command"
|
|
# test help gotcha
|
|
gdb_test "help gotcha" "Undefined command: \"gotcha\"\. Try \"help\"\." "help gotcha"
|
|
|
|
# test apropos regex
|
|
gdb_test "apropos \\\(print\[\^\[ bsiedf\\\".-\]\\\)" "handle -- Specify how to handle signals\."
|
|
# test apropos >1 word string
|
|
gdb_test "apropos handle signal" "handle -- Specify how to handle signals\."
|
|
# test apropos apropos
|
|
gdb_test "apropos apropos" "apropos -- Search for commands matching a REGEXP.*"
|