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.

7 files changed, 64 insertions, 40 deletions

diff --git a/gdb/cli/cli-cmds.c b/gdb/cli/cli-cmds.c
index 0b62622..30e0958 100644
--- a/gdb/cli/cli-cmds.c
+++ b/gdb/cli/cli-cmds.c
@@ -1948,7 +1948,8 @@ The commands below can be used to select other frames by number or address."),
   /* Define general commands.  */
 
   add_com ("pwd", class_files, pwd_command, _("\
-Print working directory.  This is used for your program as well."));
+Print working directory.\n\
+This is used for your program as well."));
 
   c = add_cmd ("cd", class_files, cd_command, _("\
 Set working directory to DIR for debugger.\n\
@@ -2077,11 +2078,11 @@ from the target."),
 				       &setlist, &showlist);
 
   add_prefix_cmd ("debug", no_class, set_debug,
-		  _("Generic command for setting gdb debugging flags"),
+		  _("Generic command for setting gdb debugging flags."),
 		  &setdebuglist, "set debug ", 0, &setlist);
 
   add_prefix_cmd ("debug", no_class, show_debug,
-		  _("Generic command for showing gdb debugging flags"),
+		  _("Generic command for showing gdb debugging flags."),
 		  &showdebuglist, "show debug ", 0, &showlist);
 
   c = add_com ("shell", class_support, shell_command, _("\
@@ -2181,7 +2182,7 @@ Show definitions of non-python/scheme user defined commands.\n\
 Argument is the name of the user defined command.\n\
 With no argument, show definitions of all user defined commands."), &showlist);
   add_com ("apropos", class_support, apropos_command, _("\
-Search for commands matching a REGEXP\n\
+Search for commands matching a REGEXP.\n\
 Usage: apropos [-v] REGEXP\n\
 Flag -v indicates to produce a verbose output, showing full documentation\n\
 of the matching commands."));
diff --git a/gdb/cli/cli-decode.c b/gdb/cli/cli-decode.c
index edea3ad..7d4b39f 100644
--- a/gdb/cli/cli-decode.c
+++ b/gdb/cli/cli-decode.c
@@ -978,7 +978,7 @@ print_doc_of_command (struct cmd_list_element *c, const char *prefix,
   if (verbose)
     fputs_highlighted (c->doc, highlight, stream);
   else
-    print_doc_line (stream, c->doc);
+    print_doc_line (stream, c->doc, false);
   fputs_filtered ("\n", stream);
 }
 
@@ -1217,9 +1217,11 @@ help_all (struct ui_file *stream)
 
 }
 
-/* Print only the first line of STR on STREAM.  */
+/* See cli-decode.h.  */
+
 void
-print_doc_line (struct ui_file *stream, const char *str)
+print_doc_line (struct ui_file *stream, const char *str,
+		bool for_value_prefix)
 {
   static char *line_buffer = 0;
   static int line_size;
@@ -1231,11 +1233,9 @@ print_doc_line (struct ui_file *stream, const char *str)
       line_buffer = (char *) xmalloc (line_size);
     }
 
-  /* Keep printing '.' or ',' not followed by a whitespace for embedded strings
-     like '.gdbinit'.  */
+  /* Searches for the first end of line or the end of STR.  */
   p = str;
-  while (*p && *p != '\n'
-	 && ((*p != '.' && *p != ',') || (p[1] && !isspace (p[1]))))
+  while (*p && *p != '\n')
     p++;
   if (p - str > line_size - 1)
     {
@@ -1244,9 +1244,18 @@ print_doc_line (struct ui_file *stream, const char *str)
       line_buffer = (char *) xmalloc (line_size);
     }
   strncpy (line_buffer, str, p - str);
-  line_buffer[p - str] = '\0';
-  if (islower (line_buffer[0]))
-    line_buffer[0] = toupper (line_buffer[0]);
+  if (for_value_prefix)
+    {
+      if (islower (line_buffer[0]))
+	line_buffer[0] = toupper (line_buffer[0]);
+      gdb_assert (p > str);
+      if (line_buffer[p - str - 1] == '.')
+	line_buffer[p - str - 1] = '\0';
+      else
+	line_buffer[p - str] = '\0';
+    }
+  else
+    line_buffer[p - str] = '\0';
   fputs_filtered (line_buffer, stream);
 }
 
@@ -1260,7 +1269,7 @@ print_help_for_command (struct cmd_list_element *c, const char *prefix,
   fprintf_styled (stream, title_style.style (),
 		  "%s%s", prefix, c->name);
   fputs_filtered (" -- ", stream);
-  print_doc_line (stream, c->doc);
+  print_doc_line (stream, c->doc, false);
   fputs_filtered ("\n", stream);
 
   if (recurse
diff --git a/gdb/cli/cli-decode.h b/gdb/cli/cli-decode.h
index 16a6ce9..2ec4a97 100644
--- a/gdb/cli/cli-decode.h
+++ b/gdb/cli/cli-decode.h
@@ -258,9 +258,14 @@ extern void apropos_cmd (struct ui_file *, struct cmd_list_element *,
 
 extern void not_just_help_class_command (const char *arg, int from_tty);
 
-/* Exported to cli/cli-setshow.c */
-
-extern void print_doc_line (struct ui_file *, const char *);
+/* Print only the first line of STR on STREAM.
+   FOR_VALUE_PREFIX true indicates that the first line is output
+   to be a prefix to show a value (see deprecated_show_value_hack):
+   the first character is printed in uppercase, and the trailing
+   dot character is not printed.  */
+
+extern void print_doc_line (struct ui_file *stream, const char *str,
+			    bool for_value_prefix);
 
 /* The enums of boolean commands.  */
 extern const char * const boolean_enums[];
diff --git a/gdb/cli/cli-logging.c b/gdb/cli/cli-logging.c
index a8b9955..9e39be1 100644
--- a/gdb/cli/cli-logging.c
+++ b/gdb/cli/cli-logging.c
@@ -207,10 +207,10 @@ _initialize_cli_logging (void)
   static struct cmd_list_element *set_logging_cmdlist, *show_logging_cmdlist;
 
   add_prefix_cmd ("logging", class_support, set_logging_command,
-		  _("Set logging options"), &set_logging_cmdlist,
+		  _("Set logging options."), &set_logging_cmdlist,
 		  "set logging ", 0, &setlist);
   add_prefix_cmd ("logging", class_support, show_logging_command,
-		  _("Show logging options"), &show_logging_cmdlist,
+		  _("Show logging options."), &show_logging_cmdlist,
 		  "show logging ", 0, &showlist);
   add_setshow_boolean_cmd ("overwrite", class_support, &logging_overwrite, _("\
 Set whether logging overwrites or appends to the log file."), _("\
diff --git a/gdb/cli/cli-option.c b/gdb/cli/cli-option.c
index eb8ef79..4ebb445 100644
--- a/gdb/cli/cli-option.c
+++ b/gdb/cli/cli-option.c
@@ -703,7 +703,6 @@ append_indented_doc (const char *doc, std::string &help)
     }
   help += "    ";
   help += p;
-  help += '\n';
 }
 
 /* Fill HELP with an auto-generated "help" string fragment for
@@ -732,8 +731,10 @@ build_help_option (gdb::array_view<const option_def> options,
       help += "\n";
       append_indented_doc (o.set_doc, help);
       if (o.help_doc != nullptr)
-	append_indented_doc (o.help_doc, help);
-      help += '\n';
+	{
+	  help += "\n";
+	  append_indented_doc (o.help_doc, help);
+	}
     }
 }
 
@@ -743,6 +744,7 @@ std::string
 build_help (const char *help_tmpl,
 	    gdb::array_view<const option_def_group> options_group)
 {
+  bool need_newlines = false;
   std::string help_str;
 
   const char *p = strstr (help_tmpl, "%OPTIONS%");
@@ -750,7 +752,13 @@ build_help (const char *help_tmpl,
 
   for (const auto &grp : options_group)
     for (const auto &opt : grp.options)
-      build_help_option (opt, help_str);
+      {
+	if (need_newlines)
+	  help_str += "\n\n";
+	else
+	  need_newlines = true;
+	build_help_option (opt, help_str);
+      }
 
   p += strlen ("%OPTIONS%");
   help_str.append (p);
diff --git a/gdb/cli/cli-setshow.c b/gdb/cli/cli-setshow.c
index 6fb3244..4053883 100644
--- a/gdb/cli/cli-setshow.c
+++ b/gdb/cli/cli-setshow.c
@@ -130,8 +130,9 @@ deprecated_show_value_hack (struct ui_file *ignore_file,
   /* If there's no command or value, don't try to print it out.  */
   if (c == NULL || value == NULL)
     return;
-  /* Print doc minus "show" at start.  */
-  print_doc_line (gdb_stdout, c->doc + 5);
+  /* Print doc minus "Show " at start.  Tell print_doc_line that
+     this is for a 'show value' prefix.  */
+  print_doc_line (gdb_stdout, c->doc + 5, true);
   switch (c->var_type)
     {
     case var_string:
diff --git a/gdb/cli/cli-style.c b/gdb/cli/cli-style.c
index fb6486b..e594e38 100644
--- a/gdb/cli/cli-style.c
+++ b/gdb/cli/cli-style.c
@@ -206,24 +206,24 @@ cli_style_option::add_setshow_commands (enum command_class theclass,
 
   add_setshow_enum_cmd ("foreground", theclass, cli_colors,
 			&m_foreground,
-			_("Set the foreground color for this property"),
-			_("Show the foreground color for this property"),
+			_("Set the foreground color for this property."),
+			_("Show the foreground color for this property."),
 			nullptr,
 			nullptr,
 			do_show_foreground,
 			&m_set_list, &m_show_list, (void *) this);
   add_setshow_enum_cmd ("background", theclass, cli_colors,
 			&m_background,
-			_("Set the background color for this property"),
-			_("Show the background color for this property"),
+			_("Set the background color for this property."),
+			_("Show the background color for this property."),
 			nullptr,
 			nullptr,
 			do_show_background,
 			&m_set_list, &m_show_list, (void *) this);
   add_setshow_enum_cmd ("intensity", theclass, cli_intensities,
 			&m_intensity,
-			_("Set the display intensity for this property"),
-			_("Show the display intensity for this property"),
+			_("Set the display intensity for this property."),
+			_("Show the display intensity for this property."),
 			nullptr,
 			nullptr,
 			do_show_intensity,
@@ -290,11 +290,11 @@ void
 _initialize_cli_style ()
 {
   add_prefix_cmd ("style", no_class, set_style, _("\
-Style-specific settings\n\
+Style-specific settings.\n\
 Configure various style-related variables, such as colors"),
 		  &style_set_list, "set style ", 0, &setlist);
   add_prefix_cmd ("style", no_class, show_style, _("\
-Style-specific settings\n\
+Style-specific settings.\n\
 Configure various style-related variables, such as colors"),
 		  &style_show_list, "show style ", 0, &showlist);
 
@@ -341,34 +341,34 @@ it was not linked against GNU Source Highlight."
 
   STYLE_ADD_SETSHOW_COMMANDS (file_name_style,
 			      _("\
-Filename display styling\n\
+Filename display styling.\n\
 Configure filename colors and display intensity."));
 
   STYLE_ADD_SETSHOW_COMMANDS (function_name_style,
 			      _("\
-Function name display styling\n\
+Function name display styling.\n\
 Configure function name colors and display intensity"));
 
   STYLE_ADD_SETSHOW_COMMANDS (variable_name_style,
 			      _("\
-Variable name display styling\n\
+Variable name display styling.\n\
 Configure variable name colors and display intensity"));
 
   STYLE_ADD_SETSHOW_COMMANDS (address_style,
 			      _("\
-Address display styling\n\
+Address display styling.\n\
 Configure address colors and display intensity"));
 
   STYLE_ADD_SETSHOW_COMMANDS (title_style,
 			      _("\
-Title display styling\n\
+Title display styling.\n\
 Configure title colors and display intensity\n\
 Some commands (such as \"apropos -v REGEXP\") use the title style to improve\n\
 readability."));
 
   STYLE_ADD_SETSHOW_COMMANDS (highlight_style,
 			      _("\
-Highlight display styling\n\
+Highlight display styling.\n\
 Configure highlight colors and display intensity\n\
 Some commands use the highlight style to draw the attention to a part\n\
 of their output."));