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  <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.

1 files changed, 37 insertions, 24 deletions

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;