From 590042fc45f857c981bee4e0c76f6b3b528a224e Mon Sep 17 00:00:00 2001 From: Philippe Waroquiers Date: Sun, 9 Jun 2019 11:16:20 +0200 Subject: Make first and last lines of 'command help documentation' consistent. 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 * 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 * gdb.base/style.exp: Update tests for help doc new invariants. * gdb.base/help.exp: Likewise. --- gdb/breakpoint.c | 61 ++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 37 insertions(+), 24 deletions(-) (limited to 'gdb/breakpoint.c') diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c index 7a1e782..9478d2d 100644 --- a/gdb/breakpoint.c +++ b/gdb/breakpoint.c @@ -15451,7 +15451,8 @@ BREAK_ARGS_HELP ("thbreak"))); set_cmd_completer (c, location_completer); add_prefix_cmd ("enable", class_breakpoint, enable_command, _("\ -Enable some breakpoints.\n\ +Enable all or some breakpoints.\n\ +Usage: enable [BREAKPOINTNUM]...\n\ Give breakpoint numbers (separated by spaces) as arguments.\n\ With no subcommand, breakpoints are enabled until you command otherwise.\n\ This is used to cancel the effect of the \"disable\" command.\n\ @@ -15461,46 +15462,54 @@ With a subcommand you can enable temporarily."), add_com_alias ("en", "enable", class_breakpoint, 1); add_prefix_cmd ("breakpoints", class_breakpoint, enable_command, _("\ -Enable some breakpoints.\n\ +Enable all or some breakpoints.\n\ +Usage: enable breakpoints [BREAKPOINTNUM]...\n\ Give breakpoint numbers (separated by spaces) as arguments.\n\ This is used to cancel the effect of the \"disable\" command.\n\ May be abbreviated to simply \"enable\"."), &enablebreaklist, "enable breakpoints ", 1, &enablelist); add_cmd ("once", no_class, enable_once_command, _("\ -Enable breakpoints for one hit. Give breakpoint numbers.\n\ +Enable some breakpoints for one hit.\n\ +Usage: enable breakpoints once BREAKPOINTNUM...\n\ If a breakpoint is hit while enabled in this fashion, it becomes disabled."), &enablebreaklist); add_cmd ("delete", no_class, enable_delete_command, _("\ -Enable breakpoints and delete when hit. Give breakpoint numbers.\n\ +Enable some breakpoints and delete when hit.\n\ +Usage: enable breakpoints delete BREAKPOINTNUM...\n\ If a breakpoint is hit while enabled in this fashion, it is deleted."), &enablebreaklist); add_cmd ("count", no_class, enable_count_command, _("\ -Enable breakpoints for COUNT hits. Give count and then breakpoint numbers.\n\ +Enable some breakpoints for COUNT hits.\n\ +Usage: enable breakpoints count COUNT BREAKPOINTNUM...\n\ If a breakpoint is hit while enabled in this fashion,\n\ the count is decremented; when it reaches zero, the breakpoint is disabled."), &enablebreaklist); add_cmd ("delete", no_class, enable_delete_command, _("\ -Enable breakpoints and delete when hit. Give breakpoint numbers.\n\ +Enable some breakpoints and delete when hit.\n\ +Usage: enable delete BREAKPOINTNUM...\n\ If a breakpoint is hit while enabled in this fashion, it is deleted."), &enablelist); add_cmd ("once", no_class, enable_once_command, _("\ -Enable breakpoints for one hit. Give breakpoint numbers.\n\ +Enable some breakpoints for one hit.\n\ +Usage: enable once BREAKPOINTNUM...\n\ If a breakpoint is hit while enabled in this fashion, it becomes disabled."), &enablelist); add_cmd ("count", no_class, enable_count_command, _("\ -Enable breakpoints for COUNT hits. Give count and then breakpoint numbers.\n\ +Enable some breakpoints for COUNT hits.\n\ +Usage: enable count COUNT BREAKPOINTNUM...\n\ If a breakpoint is hit while enabled in this fashion,\n\ the count is decremented; when it reaches zero, the breakpoint is disabled."), &enablelist); add_prefix_cmd ("disable", class_breakpoint, disable_command, _("\ -Disable some breakpoints.\n\ +Disable all or some breakpoints.\n\ +Usage: disable [BREAKPOINTNUM]...\n\ Arguments are breakpoint numbers with spaces in between.\n\ To disable all breakpoints, give no argument.\n\ A disabled breakpoint is not forgotten, but has no effect until re-enabled."), @@ -15509,7 +15518,8 @@ A disabled breakpoint is not forgotten, but has no effect until re-enabled."), add_com_alias ("disa", "disable", class_breakpoint, 1); add_cmd ("breakpoints", class_alias, disable_command, _("\ -Disable some breakpoints.\n\ +Disable all or some breakpoints.\n\ +Usage: disable breakpoints [BREAKPOINTNUM]...\n\ Arguments are breakpoint numbers with spaces in between.\n\ To disable all breakpoints, give no argument.\n\ A disabled breakpoint is not forgotten, but has no effect until re-enabled.\n\ @@ -15517,18 +15527,19 @@ This command may be abbreviated \"disable\"."), &disablelist); add_prefix_cmd ("delete", class_breakpoint, delete_command, _("\ -Delete some breakpoints or auto-display expressions.\n\ +Delete all or some breakpoints.\n\ +Usage: delete [BREAKPOINTNUM]...\n\ Arguments are breakpoint numbers with spaces in between.\n\ To delete all breakpoints, give no argument.\n\ \n\ -Also a prefix command for deletion of other GDB objects.\n\ -The \"unset\" command is also an alias for \"delete\"."), +Also a prefix command for deletion of other GDB objects."), &deletelist, "delete ", 1, &cmdlist); add_com_alias ("d", "delete", class_breakpoint, 1); add_com_alias ("del", "delete", class_breakpoint, 1); add_cmd ("breakpoints", class_alias, delete_command, _("\ -Delete some breakpoints or auto-display expressions.\n\ +Delete all or some breakpoints or auto-display expressions.\n\ +Usage: delete breakpoints [BREAKPOINTNUM]...\n\ Arguments are breakpoint numbers with spaces in between.\n\ To delete all breakpoints, give no argument.\n\ This command may be abbreviated \"delete\"."), @@ -15805,15 +15816,15 @@ Use the 'source' command in another debug session to restore them."), deprecate_cmd (c, "save tracepoints"); add_prefix_cmd ("breakpoint", class_maintenance, set_breakpoint_cmd, _("\ -Breakpoint specific settings\n\ +Breakpoint specific settings.\n\ Configure various breakpoint-specific variables such as\n\ -pending breakpoint behavior"), +pending breakpoint behavior."), &breakpoint_set_cmdlist, "set breakpoint ", 0/*allow-unknown*/, &setlist); add_prefix_cmd ("breakpoint", class_maintenance, show_breakpoint_cmd, _("\ -Breakpoint specific settings\n\ +Breakpoint specific settings.\n\ Configure various breakpoint-specific variables such as\n\ -pending breakpoint behavior"), +pending breakpoint behavior."), &breakpoint_show_cmdlist, "show breakpoint ", 0/*allow-unknown*/, &showlist); @@ -15914,16 +15925,16 @@ output stream by setting dprintf-function and dprintf-channel."), dprintf_function = xstrdup ("printf"); add_setshow_string_cmd ("dprintf-function", class_support, &dprintf_function, _("\ -Set the function to use for dynamic printf"), _("\ -Show the function to use for dynamic printf"), NULL, +Set the function to use for dynamic printf."), _("\ +Show the function to use for dynamic printf."), NULL, update_dprintf_commands, NULL, &setlist, &showlist); dprintf_channel = xstrdup (""); add_setshow_string_cmd ("dprintf-channel", class_support, &dprintf_channel, _("\ -Set the channel to use for dynamic printf"), _("\ -Show the channel to use for dynamic printf"), NULL, +Set the channel to use for dynamic printf."), _("\ +Show the channel to use for dynamic printf."), NULL, update_dprintf_commands, NULL, &setlist, &showlist); @@ -15938,8 +15949,10 @@ even if GDB disconnects or detaches from the target."), &setlist, &showlist); add_com ("agent-printf", class_vars, agent_printf_command, _("\ -agent-printf \"printf format string\", arg1, arg2, arg3, ..., argn\n\ -(target agent only) This is useful for formatted output in user-defined commands.")); +Target agent only formatted printing, like the C \"printf\" function.\n\ +Usage: agent-printf \"format string\", ARG1, ARG2, ARG3, ..., ARGN\n\ +This supports most C printf format specifications, like %s, %d, etc.\n\ +This is useful for formatted output in user-defined commands.")); automatic_hardware_breakpoints = 1; -- cgit v1.1