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, 7 insertions, 6 deletions

diff --git a/gdb/stack.c b/gdb/stack.c
index 0dd7057..c68b387 100644
--- a/gdb/stack.c
+++ b/gdb/stack.c
@@ -139,8 +139,8 @@ static const gdb::option::option_def frame_print_option_defs[] = {
     print_entry_values_choices,
     [] (frame_print_options *opt) { return &opt->print_entry_values; },
     NULL, /* show_cmd_cb */
-    N_("Set printing of function arguments at function entry"),
-    N_("Show printing of function arguments at function entry"),
+    N_("Set printing of function arguments at function entry."),
+    N_("Show printing of function arguments at function entry."),
     N_("GDB can sometimes determine the values of function arguments at entry,\n\
 in addition to their current values.  This option tells GDB whether\n\
 to print the current value, the value at entry (marked as val@entry),\n\
@@ -152,8 +152,8 @@ or both.  Note that one or both of these values may be <optimized out>."),
     print_frame_arguments_choices,
     [] (frame_print_options *opt) { return &opt->print_frame_arguments; },
     NULL, /* show_cmd_cb */
-    N_("Set printing of non-scalar frame arguments"),
-    N_("Show printing of non-scalar frame arguments"),
+    N_("Set printing of non-scalar frame arguments."),
+    N_("Show printing of non-scalar frame arguments."),
     NULL /* help_doc */
   },
 
@@ -3330,7 +3330,7 @@ A single numerical argument specifies the frame to select."),
 
   add_cmd ("address", class_stack, &frame_cmd.address,
 	   _("\
-Select and print a stack frame by stack address\n\
+Select and print a stack frame by stack address.\n\
 \n\
 Usage: frame address STACK-ADDRESS"),
 	   &frame_cmd_list);
@@ -3412,7 +3412,8 @@ Print backtrace of all stack frames, or innermost COUNT frames.\n\
 Usage: backtrace [OPTION]... [QUALIFIER]... [COUNT | -COUNT]\n\
 \n\
 Options:\n\
-%OPTIONS%\
+%OPTIONS%\n\
+\n\
 For backward compatibility, the following qualifiers are supported:\n\
 \n\
    full       - same as -full option.\n\