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, 9 insertions, 8 deletions

diff --git a/gdb/top.c b/gdb/top.c
index a9f9a38..9d4ce1f 100644
--- a/gdb/top.c
+++ b/gdb/top.c
@@ -2093,8 +2093,8 @@ init_main (void)
 
   add_setshow_string_cmd ("prompt", class_support,
 			  &top_prompt,
-			  _("Set gdb's prompt"),
-			  _("Show gdb's prompt"),
+			  _("Set gdb's prompt."),
+			  _("Show gdb's prompt."),
 			  NULL, NULL,
 			  show_prompt,
 			  &setlist, &showlist);
@@ -2126,9 +2126,9 @@ Without an argument, saving is enabled."),
 
   add_setshow_zuinteger_unlimited_cmd ("size", no_class,
 				       &history_size_setshow_var, _("\
-Set the size of the command history,"), _("\
-Show the size of the command history,"), _("\
-ie. the number of previous commands to keep a record of.\n\
+Set the size of the command history."), _("\
+Show the size of the command history."), _("\
+This is the number of previous commands to keep a record of.\n\
 If set to \"unlimited\", the number of commands kept in the history\n\
 list is unlimited.  This defaults to the value of the environment\n\
 variable \"GDBHISTSIZE\", or to 256 if this variable is not set."),
@@ -2152,8 +2152,8 @@ By default this option is set to 0."),
 			   &sethistlist, &showhistlist);
 
   add_setshow_filename_cmd ("filename", no_class, &history_filename, _("\
-Set the filename in which to record the command history"), _("\
-Show the filename in which to record the command history"), _("\
+Set the filename in which to record the command history."), _("\
+Show the filename in which to record the command history."), _("\
 (the list of previous commands of which a record is kept)."),
 			    set_history_filename,
 			    show_history_filename,
@@ -2208,7 +2208,8 @@ input settings."),
                         &setlist, &showlist);
 
   c = add_cmd ("new-ui", class_support, new_ui_command, _("\
-Create a new UI.  It takes two arguments:\n\
+Create a new UI.\n\
+Usage: new-ui INTERPRETER TTY\n\
 The first argument is the name of the interpreter to run.\n\
 The second argument is the terminal the UI runs on."), &cmdlist);
   set_cmd_completer (c, interpreter_completer);