[RFA] Make first and last lines of 'command help documentation' consistent.

Message ID 20190616195804.9427-1-philippe.waroquiers@skynet.be
State Superseded
Headers show
Series
  • [RFA] Make first and last lines of 'command help documentation' consistent.
Related show

Commit Message

Philippe Waroquiers June 16, 2019, 7:58 p.m.
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.
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.

The test gdb.base/help.exp is modified to verify these invariants
automatically for all commands compiled in GDB.

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

If you want, you might look at the new resulting help by doing the following
command in a HEAD GDB and in a GDB with this patch, and then
use emacs M-x ediff-files (or the diff tool you prefer) to review
the changes in the 'full_help.txt', checking a.o. that the
first line of the help of a command is understanble by itself.

(gdb) |apropos -v .| cat > full_help.txt

full_help.txt has a lot of small differences (but less than the
one_line_help.txt below) because:
  * excess new-lines at the end of docs have been removed.
  * missing . at end of first line have been added.

You can also produce a file with just the first line of help:
(gdb) |apropos .| cat > one_line_help.txt
The 'one_line_help.txt' contains a lot more of artificial differences,
as the HEAD GDB does not output the trailing '.' character.

gdb/ChangeLog
2019-06-16  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.  Output a specific string
	when doc string ends with a line feed to allow the testsuite
	to detect the broken invariant.
	* 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.
C	hange 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-06-16  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* gdb.base/style.exp: Update tests for help doc new invariants.
	* gdb.base/help.exp: Likewise.	Add tests to check new invariants.
---
 gdb/ada-lang.c                        | 12 +++---
 gdb/ada-tasks.c                       |  4 +-
 gdb/breakpoint.c                      | 58 +++++++++++++++++----------
 gdb/cli/cli-cmds.c                    |  9 +++--
 gdb/cli/cli-decode.c                  | 38 +++++++++++++-----
 gdb/cli/cli-decode.h                  | 11 +++--
 gdb/cli/cli-logging.c                 |  4 +-
 gdb/cli/cli-option.c                  | 16 ++++++--
 gdb/cli/cli-setshow.c                 |  5 ++-
 gdb/cli/cli-style.c                   | 28 ++++++-------
 gdb/compile/compile.c                 | 12 +++---
 gdb/corelow.c                         |  3 +-
 gdb/dwarf-index-cache.c               |  4 +-
 gdb/dwarf2read.c                      |  6 +--
 gdb/filesystem.c                      |  4 +-
 gdb/frame.c                           |  4 +-
 gdb/gnu-nat.c                         | 10 ++---
 gdb/infcall.c                         |  2 +-
 gdb/infcmd.c                          |  5 ++-
 gdb/interps.c                         |  6 +--
 gdb/language.c                        |  8 ++--
 gdb/linux-fork.c                      |  3 +-
 gdb/maint-test-options.c              |  4 +-
 gdb/maint-test-settings.c             | 48 +++++++++++-----------
 gdb/maint.c                           | 21 +++++-----
 gdb/memattr.c                         | 10 ++---
 gdb/printcmd.c                        |  9 +++--
 gdb/python/lib/gdb/function/strfns.py |  8 ++--
 gdb/ravenscar-thread.c                |  8 ++--
 gdb/record-btrace.c                   | 14 +++----
 gdb/record-full.c                     |  4 +-
 gdb/record.c                          |  6 +--
 gdb/regcache-dump.c                   |  4 +-
 gdb/regcache.c                        |  2 +-
 gdb/remote.c                          | 36 ++++++++---------
 gdb/ser-tcp.c                         | 16 ++++----
 gdb/serial.c                          |  8 ++--
 gdb/skip.c                            | 30 ++++++++------
 gdb/source.c                          |  3 ++
 gdb/stack.c                           | 13 +++---
 gdb/symfile.c                         |  4 +-
 gdb/symtab.c                          |  3 +-
 gdb/target-descriptions.c             |  9 +++--
 gdb/testsuite/gdb.base/help.exp       | 17 ++++++--
 gdb/testsuite/gdb.base/style.exp      |  4 +-
 gdb/top.c                             | 17 ++++----
 gdb/tracefile-tfile.c                 |  3 +-
 gdb/tracepoint.c                      | 20 ++++-----
 gdb/tui/tui-win.c                     |  6 +--
 gdb/utils.c                           |  8 ++--
 gdb/valprint.c                        |  2 +-
 51 files changed, 330 insertions(+), 259 deletions(-)

-- 
2.20.1

Comments

Philippe Waroquiers July 5, 2019, 8:04 p.m. | #1
Ping ?

Thanks

Philippe

On Sun, 2019-06-16 at 21:58 +0200, Philippe Waroquiers wrote:
> 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.

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

> 

> The test gdb.base/help.exp is modified to verify these invariants

> automatically for all commands compiled in GDB.

> 

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

> 

> If you want, you might look at the new resulting help by doing the following

> command in a HEAD GDB and in a GDB with this patch, and then

> use emacs M-x ediff-files (or the diff tool you prefer) to review

> the changes in the 'full_help.txt', checking a.o. that the

> first line of the help of a command is understanble by itself.

> 

> (gdb) |apropos -v .| cat > full_help.txt

> 

> full_help.txt has a lot of small differences (but less than the

> one_line_help.txt below) because:

>   * excess new-lines at the end of docs have been removed.

>   * missing . at end of first line have been added.

> 

> You can also produce a file with just the first line of help:

> (gdb) |apropos .| cat > one_line_help.txt

> The 'one_line_help.txt' contains a lot more of artificial differences,

> as the HEAD GDB does not output the trailing '.' character.

> 

> gdb/ChangeLog

> 2019-06-16  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.  Output a specific string

> 	when doc string ends with a line feed to allow the testsuite

> 	to detect the broken invariant.

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

> C	hange 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-06-16  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

> 

> 	* gdb.base/style.exp: Update tests for help doc new invariants.

> 	* gdb.base/help.exp: Likewise.	Add tests to check new invariants.

> ---

>  gdb/ada-lang.c                        | 12 +++---

>  gdb/ada-tasks.c                       |  4 +-

>  gdb/breakpoint.c                      | 58 +++++++++++++++++----------

>  gdb/cli/cli-cmds.c                    |  9 +++--

>  gdb/cli/cli-decode.c                  | 38 +++++++++++++-----

>  gdb/cli/cli-decode.h                  | 11 +++--

>  gdb/cli/cli-logging.c                 |  4 +-

>  gdb/cli/cli-option.c                  | 16 ++++++--

>  gdb/cli/cli-setshow.c                 |  5 ++-

>  gdb/cli/cli-style.c                   | 28 ++++++-------

>  gdb/compile/compile.c                 | 12 +++---

>  gdb/corelow.c                         |  3 +-

>  gdb/dwarf-index-cache.c               |  4 +-

>  gdb/dwarf2read.c                      |  6 +--

>  gdb/filesystem.c                      |  4 +-

>  gdb/frame.c                           |  4 +-

>  gdb/gnu-nat.c                         | 10 ++---

>  gdb/infcall.c                         |  2 +-

>  gdb/infcmd.c                          |  5 ++-

>  gdb/interps.c                         |  6 +--

>  gdb/language.c                        |  8 ++--

>  gdb/linux-fork.c                      |  3 +-

>  gdb/maint-test-options.c              |  4 +-

>  gdb/maint-test-settings.c             | 48 +++++++++++-----------

>  gdb/maint.c                           | 21 +++++-----

>  gdb/memattr.c                         | 10 ++---

>  gdb/printcmd.c                        |  9 +++--

>  gdb/python/lib/gdb/function/strfns.py |  8 ++--

>  gdb/ravenscar-thread.c                |  8 ++--

>  gdb/record-btrace.c                   | 14 +++----

>  gdb/record-full.c                     |  4 +-

>  gdb/record.c                          |  6 +--

>  gdb/regcache-dump.c                   |  4 +-

>  gdb/regcache.c                        |  2 +-

>  gdb/remote.c                          | 36 ++++++++---------

>  gdb/ser-tcp.c                         | 16 ++++----

>  gdb/serial.c                          |  8 ++--

>  gdb/skip.c                            | 30 ++++++++------

>  gdb/source.c                          |  3 ++

>  gdb/stack.c                           | 13 +++---

>  gdb/symfile.c                         |  4 +-

>  gdb/symtab.c                          |  3 +-

>  gdb/target-descriptions.c             |  9 +++--

>  gdb/testsuite/gdb.base/help.exp       | 17 ++++++--

>  gdb/testsuite/gdb.base/style.exp      |  4 +-

>  gdb/top.c                             | 17 ++++----

>  gdb/tracefile-tfile.c                 |  3 +-

>  gdb/tracepoint.c                      | 20 ++++-----

>  gdb/tui/tui-win.c                     |  6 +--

>  gdb/utils.c                           |  8 ++--

>  gdb/valprint.c                        |  2 +-

>  51 files changed, 330 insertions(+), 259 deletions(-)

> 

> diff --git a/gdb/ada-lang.c b/gdb/ada-lang.c

> index 1b5f18316f..c6c702459d 100644

> --- a/gdb/ada-lang.c

> +++ b/gdb/ada-lang.c

> @@ -14380,7 +14380,7 @@ _initialize_ada_language (void)

>    initialize_ada_catchpoint_ops ();

>  

>    add_prefix_cmd ("ada", no_class, set_ada_command,

> -                  _("Prefix command for changing Ada-specific settings"),

> +                  _("Prefix command for changing Ada-specific settings."),

>                    &set_ada_list, "set ada ", 0, &setlist);

>  

>    add_prefix_cmd ("ada", no_class, show_ada_command,

> @@ -14389,8 +14389,8 @@ _initialize_ada_language (void)

>  

>    add_setshow_boolean_cmd ("trust-PAD-over-XVS", class_obscure,

>                             &trust_pad_over_xvs, _("\

> -Enable or disable an optimization trusting PAD types over XVS types"), _("\

> -Show whether an optimization trusting PAD types over XVS types is activated"),

> +Enable or disable an optimization trusting PAD types over XVS types."), _("\

> +Show whether an optimization trusting PAD types over XVS types is activated."),

>                             _("\

>  This is related to the encoding used by the GNAT compiler.  The debugger\n\

>  should normally trust the contents of PAD types, but certain older versions\n\

> @@ -14404,9 +14404,9 @@ this option to \"off\" unless necessary."),

>    add_setshow_boolean_cmd ("print-signatures", class_vars,

>  			   &print_signatures, _("\

>  Enable or disable the output of formal and return types for functions in the \

> -overloads selection menu"), _("\

> +overloads selection menu."), _("\

>  Show whether the output of formal and return types for functions in the \

> -overloads selection menu is activated"),

> +overloads selection menu is activated."),

>  			   NULL, NULL, NULL, &set_ada_list, &show_ada_list);

>  

>    add_catch_command ("exception", _("\

> @@ -14468,7 +14468,7 @@ the regular expression are listed."));

>                    0/*allow-unknown*/, &maintenance_set_cmdlist);

>  

>    add_prefix_cmd ("ada", class_maintenance, maint_show_ada_cmd,

> -		  _("Show Ada maintenance-related variables"),

> +		  _("Show Ada maintenance-related variables."),

>                    &maint_show_ada_cmdlist, "maintenance show ada ",

>                    0/*allow-unknown*/, &maintenance_show_cmdlist);

>  

> diff --git a/gdb/ada-tasks.c b/gdb/ada-tasks.c

> index 9c07f0ca22..f34b5b81e7 100644

> --- a/gdb/ada-tasks.c

> +++ b/gdb/ada-tasks.c

> @@ -1413,9 +1413,9 @@ _initialize_tasks (void)

>  

>    /* Some new commands provided by this module.  */

>    add_info ("tasks", info_tasks_command,

> -            _("Provide information about all known Ada tasks"));

> +            _("Provide information about all known Ada tasks."));

>    add_cmd ("task", class_run, task_command,

>             _("Use this command to switch between Ada tasks.\n\

> -Without argument, this command simply prints the current task ID"),

> +Without argument, this command simply prints the current task ID."),

>             &cmdlist);

>  }

> diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c

> index ccd778b7a1..8e5a0d3dc4 100644

> --- a/gdb/breakpoint.c

> +++ b/gdb/breakpoint.c

> @@ -15483,7 +15483,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\

> @@ -15493,46 +15494,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."),

> @@ -15541,7 +15550,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\

> @@ -15549,7 +15559,8 @@ 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 or auto-display expressions.\n\

> +Usage: delete [BREAKPOINTNUM]...\n\

>  Arguments are breakpoint numbers with spaces in between.\n\

>  To delete all breakpoints, give no argument.\n\

>  \n\

> @@ -15560,7 +15571,8 @@ The \"unset\" command is also an alias for \"delete\"."),

>    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\"."),

> @@ -15837,15 +15849,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);

>  

> @@ -15946,16 +15958,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);

>  

> @@ -15970,8 +15982,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;

>  

> diff --git a/gdb/cli/cli-cmds.c b/gdb/cli/cli-cmds.c

> index 62f4d7f0c5..5a17673f71 100644

> --- a/gdb/cli/cli-cmds.c

> +++ b/gdb/cli/cli-cmds.c

> @@ -1769,7 +1769,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\

> @@ -1881,11 +1882,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, _("\

> @@ -1984,7 +1985,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 a6ddd8cc6d..21d2a7b1f6 100644

> --- a/gdb/cli/cli-decode.c

> +++ b/gdb/cli/cli-decode.c

> @@ -978,8 +978,15 @@ 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);

> +

> +  /* Checks that the documentation does not help with a new line.

> +     If it does, output a special marker string that gdb.base/help.exp

> +     will detect.  */

> +  if (c->doc[strlen (c->doc) - 1] == '\n')

> +    fprintf_filtered (stream, "END_OF_LINE@END_OF_DOC %s%s\n",

> +		      prefix, c->name);

>  }

>  

>  /* Recursively walk the commandlist structures, and print out the

> @@ -1217,9 +1224,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 +1240,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 +1251,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 +1276,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 05280d9d22..b72970b635 100644

> --- a/gdb/cli/cli-decode.h

> +++ b/gdb/cli/cli-decode.h

> @@ -257,9 +257,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 a8b9955c57..9e39be197b 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 9a53ec0592..96243c9ec6 100644

> --- a/gdb/cli/cli-option.c

> +++ b/gdb/cli/cli-option.c

> @@ -611,7 +611,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

> @@ -640,8 +639,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);

> +	}

>      }

>  }

>  

> @@ -651,6 +652,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%");

> @@ -658,7 +660,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 8199fa7c0b..b68ce99200 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 fb6486bfdf..e594e38cd6 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."));

> diff --git a/gdb/compile/compile.c b/gdb/compile/compile.c

> index 25d0bfe602..f82af8679c 100644

> --- a/gdb/compile/compile.c

> +++ b/gdb/compile/compile.c

> @@ -978,6 +978,7 @@ Usage: compile code [OPTION]... [CODE]\n\

>  \n\

>  Options:\n\

>  %OPTIONS%\n\

> +\n\

>  The source code may be specified as a simple one line expression, e.g.:\n\

>  \n\

>      compile code printf(\"Hello world\\n\");\n\

> @@ -1017,7 +1018,8 @@ Evaluate EXPR by using the compiler and print result.\n\

>  Usage: compile print [[OPTION]... --] [/FMT] [EXPR]\n\

>  \n\

>  Options:\n\

> -%OPTIONS%\

> +%OPTIONS%\n\

> +\n\

>  Note: because this command accepts arbitrary expressions, if you\n\

>  specify any command option, you must use a double dash (\"--\")\n\

>  to mark the end of option processing.  E.g.: \"compile print -o -- myobj\".\n\

> @@ -1049,8 +1051,8 @@ When on, compile command debugging is enabled."),

>  

>    add_setshow_string_cmd ("compile-args", class_support,

>  			  &compile_args,

> -			  _("Set compile command GCC command-line arguments"),

> -			  _("Show compile command GCC command-line arguments"),

> +			  _("Set compile command GCC command-line arguments."),

> +			  _("Show compile command GCC command-line arguments."),

>  			  _("\

>  Use options like -I (include file directory) or ABI settings.\n\

>  String quoting is parsed like in shell, for example:\n\

> @@ -1078,9 +1080,9 @@ String quoting is parsed like in shell, for example:\n\

>    add_setshow_optional_filename_cmd ("compile-gcc", class_support,

>  				     &compile_gcc,

>  				     _("Set compile command "

> -				       "GCC driver filename"),

> +				       "GCC driver filename."),

>  				     _("Show compile command "

> -				       "GCC driver filename"),

> +				       "GCC driver filename."),

>  				     _("\

>  It should be absolute filename of the gcc executable.\n\

>  If empty the default target triplet will be searched in $PATH."),

> diff --git a/gdb/corelow.c b/gdb/corelow.c

> index 9fcc2d2372..511fea81fa 100644

> --- a/gdb/corelow.c

> +++ b/gdb/corelow.c

> @@ -56,7 +56,8 @@ static core_fns *sniff_core_bfd (gdbarch *core_gdbarch,

>  static const target_info core_target_info = {

>    "core",

>    N_("Local core dump file"),

> -  N_("Use a core file as a target.  Specify the filename of the core file.")

> +  N_("Use a core file as a target.\n\

> +Specify the filename of the core file.")

>  };

>  

>  class core_target final : public process_stratum_target

> diff --git a/gdb/dwarf-index-cache.c b/gdb/dwarf-index-cache.c

> index 7222f0528d..a036f5b207 100644

> --- a/gdb/dwarf-index-cache.c

> +++ b/gdb/dwarf-index-cache.c

> @@ -317,12 +317,12 @@ _initialize_index_cache ()

>  

>    /* set index-cache */

>    add_prefix_cmd ("index-cache", class_files, set_index_cache_command,

> -		  _("Set index-cache options"), &set_index_cache_prefix_list,

> +		  _("Set index-cache options."), &set_index_cache_prefix_list,

>  		  "set index-cache ", false, &setlist);

>  

>    /* show index-cache */

>    add_prefix_cmd ("index-cache", class_files, show_index_cache_command,

> -		  _("Show index-cache options"), &show_index_cache_prefix_list,

> +		  _("Show index-cache options."), &show_index_cache_prefix_list,

>  		  "show index-cache ", false, &showlist);

>  

>    /* set index-cache on */

> diff --git a/gdb/dwarf2read.c b/gdb/dwarf2read.c

> index 4cf9fcfa21..49cd1e8a62 100644

> --- a/gdb/dwarf2read.c

> +++ b/gdb/dwarf2read.c

> @@ -25794,13 +25794,13 @@ _initialize_dwarf2_read (void)

>  {

>    add_prefix_cmd ("dwarf", class_maintenance, set_dwarf_cmd, _("\

>  Set DWARF specific variables.\n\

> -Configure DWARF variables such as the cache size"),

> +Configure DWARF variables such as the cache size."),

>                    &set_dwarf_cmdlist, "maintenance set dwarf ",

>                    0/*allow-unknown*/, &maintenance_set_cmdlist);

>  

>    add_prefix_cmd ("dwarf", class_maintenance, show_dwarf_cmd, _("\

> -Show DWARF specific variables\n\

> -Show DWARF variables such as the cache size"),

> +Show DWARF specific variables.\n\

> +Show DWARF variables such as the cache size."),

>                    &show_dwarf_cmdlist, "maintenance show dwarf ",

>                    0/*allow-unknown*/, &maintenance_show_cmdlist);

>  

> diff --git a/gdb/filesystem.c b/gdb/filesystem.c

> index fdc4713007..a942e7067d 100644

> --- a/gdb/filesystem.c

> +++ b/gdb/filesystem.c

> @@ -83,8 +83,8 @@ _initialize_filesystem (void)

>  			class_files,

>  			target_file_system_kinds,

>  			&target_file_system_kind, _("\

> -Set assumed file system kind for target reported file names"), _("\

> -Show assumed file system kind for target reported file names"),

> +Set assumed file system kind for target reported file names."), _("\

> +Show assumed file system kind for target reported file names."),

>  			_("\

>  If `unix', target file names (e.g., loaded shared library file names)\n\

>  starting the forward slash (`/') character are considered absolute,\n\

> diff --git a/gdb/frame.c b/gdb/frame.c

> index 84e0397db9..adac24f68c 100644

> --- a/gdb/frame.c

> +++ b/gdb/frame.c

> @@ -2949,8 +2949,8 @@ Configure backtrace variables such as the backtrace limit"),

>  		  &set_backtrace_cmdlist, "set backtrace ",

>  		  0/*allow-unknown*/, &setlist);

>    add_prefix_cmd ("backtrace", class_maintenance, show_backtrace_cmd, _("\

> -Show backtrace specific variables\n\

> -Show backtrace variables such as the backtrace limit"),

> +Show backtrace specific variables.\n\

> +Show backtrace variables such as the backtrace limit."),

>  		  &show_backtrace_cmdlist, "show backtrace ",

>  		  0/*allow-unknown*/, &showlist);

>  

> diff --git a/gdb/gnu-nat.c b/gdb/gnu-nat.c

> index 5eeac9270a..5692ac5132 100644

> --- a/gdb/gnu-nat.c

> +++ b/gdb/gnu-nat.c

> @@ -3312,15 +3312,15 @@ This is the same as setting `task pause', `exceptions', and\n\

>  

>    /* Commands to show information about the task's ports.  */

>    add_info ("send-rights", info_send_rights_cmd,

> -	    _("Show information about the task's send rights"));

> +	    _("Show information about the task's send rights."));

>    add_info ("receive-rights", info_recv_rights_cmd,

> -	    _("Show information about the task's receive rights"));

> +	    _("Show information about the task's receive rights."));

>    add_info ("port-rights", info_port_rights_cmd,

> -	    _("Show information about the task's port rights"));

> +	    _("Show information about the task's port rights."));

>    add_info ("port-sets", info_port_sets_cmd,

> -	    _("Show information about the task's port sets"));

> +	    _("Show information about the task's port sets."));

>    add_info ("dead-names", info_dead_names_cmd,

> -	    _("Show information about the task's dead names"));

> +	    _("Show information about the task's dead names."));

>    add_info_alias ("ports", "port-rights", 1);

>    add_info_alias ("port", "port-rights", 1);

>    add_info_alias ("psets", "port-sets", 1);

> diff --git a/gdb/infcall.c b/gdb/infcall.c

> index 84092d37e6..be99673f67 100644

> --- a/gdb/infcall.c

> +++ b/gdb/infcall.c

> @@ -1388,7 +1388,7 @@ will result in an error."),

>    add_setshow_boolean_cmd ("coerce-float-to-double", class_obscure,

>  			   &coerce_float_to_double_p, _("\

>  Set coercion of floats to doubles when calling functions."), _("\

> -Show coercion of floats to doubles when calling functions"), _("\

> +Show coercion of floats to doubles when calling functions."), _("\

>  Variables of type float should generally be converted to doubles before\n\

>  calling an unprototyped function, and left alone when calling a prototyped\n\

>  function.  However, some older debug info formats do not provide enough\n\

> diff --git a/gdb/infcmd.c b/gdb/infcmd.c

> index afd7bb5a54..5361f1c000 100644

> --- a/gdb/infcmd.c

> +++ b/gdb/infcmd.c

> @@ -3319,6 +3319,7 @@ reason)."));

>    add_com_alias ("s", "step", class_run, 1);

>  

>    c = add_com ("until", class_run, until_command, _("\

> +Execute until past the current line or past a LOCATION.\n\

>  Execute until the program reaches a source line greater than the current\n\

>  or a specified location (same args as break command) within the current \

>  frame."));

> @@ -3394,10 +3395,10 @@ in the named register groups."));

>  	    _("Execution status of the program."));

>  

>    add_info ("float", info_float_command,

> -	    _("Print the status of the floating point unit"));

> +	    _("Print the status of the floating point unit."));

>  

>    add_info ("vector", info_vector_command,

> -	    _("Print the status of the vector unit"));

> +	    _("Print the status of the vector unit."));

>  

>    add_prefix_cmd ("proc", class_info, info_proc_cmd,

>  		  _("\

> diff --git a/gdb/interps.c b/gdb/interps.c

> index 363502e767..f2f137ca91 100644

> --- a/gdb/interps.c

> +++ b/gdb/interps.c

> @@ -378,7 +378,7 @@ interpreter_exec_cmd (const char *args, int from_tty)

>    nrules = prules.count ();

>  

>    if (nrules < 2)

> -    error (_("Usage: interpreter-exec INTERPRETER [ COMMAND... ]"));

> +    error (_("Usage: interpreter-exec INTERPRETER COMMAND..."));

>  

>    old_interp = ui_interp->current_interpreter;

>  

> @@ -448,8 +448,8 @@ _initialize_interpreter (void)

>    c = add_cmd ("interpreter-exec", class_support,

>  	       interpreter_exec_cmd, _("\

>  Execute a command in an interpreter.\n\

> -It takes two arguments:\n\

> +Usage: interpreter-exec INTERPRETER COMMAND...\n\

>  The first argument is the name of the interpreter to use.\n\

> -The second argument is the command to execute."), &cmdlist);

> +The following arguments are the commands to execute."), &cmdlist);

>    set_cmd_completer (c, interpreter_completer);

>  }

> diff --git a/gdb/language.c b/gdb/language.c

> index a7c09ccd6d..de3b59cb72 100644

> --- a/gdb/language.c

> +++ b/gdb/language.c

> @@ -1172,16 +1172,16 @@ _initialize_language (void)

>  

>    add_setshow_enum_cmd ("range", class_support, type_or_range_names,

>  			&range,

> -			_("Set range checking.  (on/warn/off/auto)"),

> -			_("Show range checking.  (on/warn/off/auto)"),

> +			_("Set range checking (on/warn/off/auto)."),

> +			_("Show range checking (on/warn/off/auto)."),

>  			NULL, set_range_command,

>  			show_range_command,

>  			&setchecklist, &showchecklist);

>  

>    add_setshow_enum_cmd ("case-sensitive", class_support, case_sensitive_names,

>  			&case_sensitive, _("\

> -Set case sensitivity in name search.  (on/off/auto)"), _("\

> -Show case sensitivity in name search.  (on/off/auto)"), _("\

> +Set case sensitivity in name search (on/off/auto)."), _("\

> +Show case sensitivity in name search (on/off/auto)."), _("\

>  For Fortran the default is off; for other languages the default is on."),

>  			set_case_command,

>  			show_case_command,

> diff --git a/gdb/linux-fork.c b/gdb/linux-fork.c

> index d323a716e3..160ddb6cbc 100644

> --- a/gdb/linux-fork.c

> +++ b/gdb/linux-fork.c

> @@ -765,7 +765,8 @@ Fork a duplicate process (experimental)."));

>       process.  */

>  

>    add_com ("restart", class_obscure, restart_command, _("\

> -restart N: restore program context from a checkpoint.\n\

> +Restore program context from a checkpoint.\n\

> +Usage: restart N\n\

>  Argument N is checkpoint ID, as displayed by 'info checkpoints'."));

>  

>    /* Delete checkpoint command: kill the process and remove it from

> diff --git a/gdb/maint-test-options.c b/gdb/maint-test-options.c

> index 599155cbfe..c70a321b8a 100644

> --- a/gdb/maint-test-options.c

> +++ b/gdb/maint-test-options.c

> @@ -398,8 +398,8 @@ Command used for testing options processing.\n\

>  Usage: maint test-options require-delimiter [[OPTION]... --] [OPERAND]...\n\

>  \n\

>  Options:\n\

> -\n\

>  %OPTIONS%\n\

> +\n\

>  If you specify any command option, you must use a double dash (\"--\")\n\

>  to mark the end of option processing."),

>  			       def_group);

> @@ -410,7 +410,6 @@ Command used for testing options processing.\n\

>  Usage: maint test-options unknown-is-error [OPTION]... [OPERAND]...\n\

>  \n\

>  Options:\n\

> -\n\

>  %OPTIONS%"),

>  			       def_group);

>  

> @@ -420,7 +419,6 @@ Command used for testing options processing.\n\

>  Usage: maint test-options unknown-is-operand [OPTION]... [OPERAND]...\n\

>  \n\

>  Options:\n\

> -\n\

>  %OPTIONS%"),

>  			       def_group);

>  

> diff --git a/gdb/maint-test-settings.c b/gdb/maint-test-settings.c

> index fa13519eb9..e339761bec 100644

> --- a/gdb/maint-test-settings.c

> +++ b/gdb/maint-test-settings.c

> @@ -133,8 +133,8 @@ Show GDB internal variables used for set/show command infrastructure testing."),

>  

>    add_setshow_boolean_cmd ("boolean", class_maintenance,

>  			   &maintenance_test_settings_boolean, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>  			   nullptr, /* help_doc */

>  			   nullptr, /* set_cmd */

>  			   maintenance_test_settings_show_value_cmd,

> @@ -143,8 +143,8 @@ command used for internal testing"),

>  

>    add_setshow_auto_boolean_cmd ("auto-boolean", class_maintenance,

>  				&maintenance_test_settings_auto_boolean, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>  				nullptr, /* help_doc */

>  				nullptr, /* set_cmd */

>  				maintenance_test_settings_show_value_cmd,

> @@ -153,8 +153,8 @@ command used for internal testing"),

>  

>    add_setshow_uinteger_cmd ("uinteger", class_maintenance,

>  			   &maintenance_test_settings_uinteger, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>  			   nullptr, /* help_doc */

>  			   nullptr, /* set_cmd */

>  			   maintenance_test_settings_show_value_cmd,

> @@ -163,8 +163,8 @@ command used for internal testing"),

>  

>    add_setshow_integer_cmd ("integer", class_maintenance,

>  			   &maintenance_test_settings_integer, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>  			   nullptr, /* help_doc */

>  			   nullptr, /* set_cmd */

>  			   maintenance_test_settings_show_value_cmd,

> @@ -173,8 +173,8 @@ command used for internal testing"),

>  

>    add_setshow_string_cmd ("string", class_maintenance,

>       &maintenance_test_settings_string, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>       nullptr, /* help_doc */

>       nullptr, /* set_cmd */

>       maintenance_test_settings_show_value_cmd,

> @@ -184,8 +184,8 @@ command used for internal testing"),

>    add_setshow_string_noescape_cmd

>      ("string-noescape", class_maintenance,

>       &maintenance_test_settings_string_noescape, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>       nullptr, /* help_doc */

>       nullptr, /* set_cmd */

>       maintenance_test_settings_show_value_cmd,

> @@ -195,8 +195,8 @@ command used for internal testing"),

>    add_setshow_optional_filename_cmd

>      ("optional-filename", class_maintenance,

>       &maintenance_test_settings_optional_filename, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>       nullptr, /* help_doc */

>       nullptr, /* set_cmd */

>       maintenance_test_settings_show_value_cmd,

> @@ -205,8 +205,8 @@ command used for internal testing"),

>  

>    add_setshow_filename_cmd ("filename", class_maintenance,

>  			    &maintenance_test_settings_filename, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>  			    nullptr, /* help_doc */

>  			    nullptr, /* set_cmd */

>  			    maintenance_test_settings_show_value_cmd,

> @@ -215,8 +215,8 @@ command used for internal testing"),

>  

>    add_setshow_zinteger_cmd ("zinteger", class_maintenance,

>  			    &maintenance_test_settings_zinteger, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>  			    nullptr, /* help_doc */

>  			    nullptr, /* set_cmd */

>  			    maintenance_test_settings_show_value_cmd,

> @@ -225,8 +225,8 @@ command used for internal testing"),

>  

>    add_setshow_zuinteger_cmd ("zuinteger", class_maintenance,

>  			     &maintenance_test_settings_zuinteger, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>  			     nullptr, /* help_doc */

>  			     nullptr, /* set_cmd */

>  			     maintenance_test_settings_show_value_cmd,

> @@ -236,8 +236,8 @@ command used for internal testing"),

>    add_setshow_zuinteger_unlimited_cmd

>      ("zuinteger-unlimited", class_maintenance,

>       &maintenance_test_settings_zuinteger_unlimited, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>       nullptr, /* help_doc */

>       nullptr, /* set_cmd */

>       maintenance_test_settings_show_value_cmd,

> @@ -247,8 +247,8 @@ command used for internal testing"),

>    add_setshow_enum_cmd ("enum", class_maintenance,

>  			maintenance_test_settings_enums,

>  			&maintenance_test_settings_enum, _("\

> -command used for internal testing"), _("\

> -command used for internal testing"),

> +command used for internal testing."), _("\

> +command used for internal testing."),

>  			nullptr, /* help_doc */

>  			nullptr, /* set_cmd */

>  			maintenance_test_settings_show_value_cmd,

> diff --git a/gdb/maint.c b/gdb/maint.c

> index aaabb35224..12e0e36ea9 100644

> --- a/gdb/maint.c

> +++ b/gdb/maint.c

> @@ -993,7 +993,7 @@ Commands for showing internal info about the program being debugged."),

>    add_alias_cmd ("i", "info", class_maintenance, 1, &maintenancelist);

>  

>    add_cmd ("sections", class_maintenance, maintenance_info_sections, _("\

> -List the BFD sections of the exec and core files. \n\

> +List the BFD sections of the exec and core files.\n\

>  Arguments may be any combination of:\n\

>  	[one or more section names]\n\

>  	ALLOC LOAD RELOC READONLY CODE DATA ROM CONSTRUCTOR\n\

> @@ -1137,21 +1137,22 @@ Commands for checking internal gdb state."),

>  	   &maintenancelist);

>  

>    add_cmd ("deprecate", class_maintenance, maintenance_deprecate, _("\

> -Deprecate a command.  Note that this is just in here so the \n\

> -testsuite can check the command deprecator. You probably shouldn't use this,\n\

> -rather you should use the C function deprecate_cmd().  If you decide you \n\

> -want to use it: maintenance deprecate 'commandname' \"replacement\". The \n\

> -replacement is optional."), &maintenancelist);

> +Deprecate a command (for testing purposes).\n\

> +Usage: maintenance deprecate COMMANDNAME [\"REPLACEMENT\"]\n\

> +This is used by the testsuite to check the command deprecator.\n\

> +You probably shouldn't use this,\n\

> +rather you should use the C function deprecate_cmd()."), &maintenancelist);

>  

>    add_cmd ("undeprecate", class_maintenance, maintenance_undeprecate, _("\

> -Undeprecate a command.  Note that this is just in here so the \n\

> -testsuite can check the command deprecator. You probably shouldn't use this,\n\

> -If you decide you want to use it: maintenance undeprecate 'commandname'"),

> +Undeprecate a command (for testing purposes).\n\

> +Usage: maintenance undeprecate COMMANDNAME\n\

> +This is used by the testsuite to check the command deprecator.\n\

> +You probably shouldn't use this."),

>  	   &maintenancelist);

>  

>    add_cmd ("selftest", class_maintenance, maintenance_selftest, _("\

>  Run gdb's unit tests.\n\

> -Usage: maintenance selftest [filter]\n\

> +Usage: maintenance selftest [FILTER]\n\

>  This will run any unit tests that were built in to gdb.\n\

>  If a filter is given, only the tests with that value in their name will ran."),

>  	   &maintenancelist);

> diff --git a/gdb/memattr.c b/gdb/memattr.c

> index 858a41abfb..cf819866b8 100644

> --- a/gdb/memattr.c

> +++ b/gdb/memattr.c

> @@ -598,8 +598,8 @@ void

>  _initialize_mem (void)

>  {

>    add_com ("mem", class_vars, mem_command, _("\

> -Define attributes for memory region or reset memory region handling to\n\

> -target-based.\n\

> +Define attributes for memory region or reset memory region handling to "

> +"target-based.\n\

>  Usage: mem auto\n\

>         mem LOW HIGH [MODE WIDTH CACHE],\n\

>  where MODE  may be rw (read/write), ro (read-only) or wo (write-only),\n\

> @@ -625,14 +625,14 @@ Usage: delete mem [ID]...\n\

>  Do \"info mem\" to see current list of IDs."), &deletelist);

>  

>    add_info ("mem", info_mem_command,

> -	    _("Memory region attributes"));

> +	    _("Memory region attributes."));

>  

>    add_prefix_cmd ("mem", class_vars, dummy_cmd, _("\

> -Memory regions settings"),

> +Memory regions settings."),

>  		  &mem_set_cmdlist, "set mem ",

>  		  0/* allow-unknown */, &setlist);

>    add_prefix_cmd ("mem", class_vars, dummy_cmd, _("\

> -Memory regions settings"),

> +Memory regions settings."),

>  		  &mem_show_cmdlist, "show mem  ",

>  		  0/* allow-unknown */, &showlist);

>  

> diff --git a/gdb/printcmd.c b/gdb/printcmd.c

> index 0509360581..5a61615c70 100644

> --- a/gdb/printcmd.c

> +++ b/gdb/printcmd.c

> @@ -2751,7 +2751,7 @@ Usage: output EXP\n\

>  This is useful in user-defined commands."));

>  

>    add_prefix_cmd ("set", class_vars, set_command, _("\

> -Evaluate expression EXP and assign result to variable VAR\n\

> +Evaluate expression EXP and assign result to variable VAR.\n\

>  Usage: set VAR = EXP\n\

>  This uses assignment syntax appropriate for the current language\n\

>  (VAR = EXP or VAR := EXP for example).\n\

> @@ -2765,7 +2765,7 @@ You can see these environment settings with the \"show\" command."),

>  		  &setlist, "set ", 1, &cmdlist);

>    if (dbx_commands)

>      add_com ("assign", class_vars, set_command, _("\

> -Evaluate expression EXP and assign result to variable VAR\n\

> +Evaluate expression EXP and assign result to variable VAR.\n\

>  Usage: assign VAR = EXP\n\

>  This uses assignment syntax appropriate for the current language\n\

>  (VAR = EXP or VAR := EXP for example).\n\

> @@ -2786,7 +2786,7 @@ history, if it is not void."));

>    set_cmd_completer_handle_brkchars (c, print_command_completer);

>  

>    add_cmd ("variable", class_vars, set_command, _("\

> -Evaluate expression EXP and assign result to variable VAR\n\

> +Evaluate expression EXP and assign result to variable VAR.\n\

>  Usage: set variable VAR = EXP\n\

>  This uses assignment syntax appropriate for the current language\n\

>  (VAR = EXP or VAR := EXP for example).\n\

> @@ -2804,7 +2804,8 @@ Print value of expression EXP.\n\

>  Usage: print [[OPTION]... --] [/FMT] [EXP]\n\

>  \n\

>  Options:\n\

> -%OPTIONS%\

> +%OPTIONS%\n\

> +\n\

>  Note: because this command accepts arbitrary expressions, if you\n\

>  specify any command option, you must use a double dash (\"--\")\n\

>  to mark the end of option processing.  E.g.: \"print -o -- myobj\".\n\

> diff --git a/gdb/python/lib/gdb/function/strfns.py b/gdb/python/lib/gdb/function/strfns.py

> index d29ff61d6c..c56957bdb2 100644

> --- a/gdb/python/lib/gdb/function/strfns.py

> +++ b/gdb/python/lib/gdb/function/strfns.py

> @@ -21,7 +21,7 @@ import re

>  

>  

>  class _MemEq(gdb.Function):

> -  """$_memeq - compare bytes of memory

> +  """$_memeq - compare bytes of memory.

>  

>  Usage: $_memeq (A, B, LEN)

>  

> @@ -44,7 +44,7 @@ Returns:

>  

>  

>  class _StrLen(gdb.Function):

> -  """$_strlen - compute string length

> +  """$_strlen - compute string length.

>  

>  Usage: $_strlen (A)

>  

> @@ -59,7 +59,7 @@ Returns:

>  

>  

>  class _StrEq(gdb.Function):

> -  """$_streq - check string equality

> +  """$_streq - check string equality.

>  

>  Usage: $_streq (A, B)

>  

> @@ -77,7 +77,7 @@ Example (amd64-linux):

>  

>  

>  class _RegEx(gdb.Function):

> -  """$_regex - check if a string matches a regular expression

> +  """$_regex - check if a string matches a regular expression.

>  

>  Usage: $_regex (STRING, REGEX)

>  

> diff --git a/gdb/ravenscar-thread.c b/gdb/ravenscar-thread.c

> index 6636a89554..f217d949f6 100644

> --- a/gdb/ravenscar-thread.c

> +++ b/gdb/ravenscar-thread.c

> @@ -601,17 +601,17 @@ _initialize_ravenscar ()

>    gdb::observers::inferior_created.attach (ravenscar_inferior_created);

>  

>    add_prefix_cmd ("ravenscar", no_class, set_ravenscar_command,

> -                  _("Prefix command for changing Ravenscar-specific settings"),

> +                  _("Prefix command for changing Ravenscar-specific settings."),

>                    &set_ravenscar_list, "set ravenscar ", 0, &setlist);

>  

>    add_prefix_cmd ("ravenscar", no_class, show_ravenscar_command,

> -                  _("Prefix command for showing Ravenscar-specific settings"),

> +                  _("Prefix command for showing Ravenscar-specific settings."),

>                    &show_ravenscar_list, "show ravenscar ", 0, &showlist);

>  

>    add_setshow_boolean_cmd ("task-switching", class_obscure,

>                             &ravenscar_task_support, _("\

> -Enable or disable support for GNAT Ravenscar tasks"), _("\

> -Show whether support for GNAT Ravenscar tasks is enabled"),

> +Enable or disable support for GNAT Ravenscar tasks."), _("\

> +Show whether support for GNAT Ravenscar tasks is enabled."),

>                             _("\

>  Enable or disable support for task/thread switching with the GNAT\n\

>  Ravenscar run-time library for bareboard configuration."),

> diff --git a/gdb/record-btrace.c b/gdb/record-btrace.c

> index 21085d5c62..a2a1e9c6dd 100644

> --- a/gdb/record-btrace.c

> +++ b/gdb/record-btrace.c

> @@ -3170,11 +3170,11 @@ This format may not be available on all processors."),

>    add_alias_cmd ("pt", "btrace pt", class_obscure, 1, &record_cmdlist);

>  

>    add_prefix_cmd ("btrace", class_support, cmd_set_record_btrace,

> -		  _("Set record options"), &set_record_btrace_cmdlist,

> +		  _("Set record options."), &set_record_btrace_cmdlist,

>  		  "set record btrace ", 0, &set_record_cmdlist);

>  

>    add_prefix_cmd ("btrace", class_support, cmd_show_record_btrace,

> -		  _("Show record options"), &show_record_btrace_cmdlist,

> +		  _("Show record options."), &show_record_btrace_cmdlist,

>  		  "show record btrace ", 0, &show_record_cmdlist);

>  

>    add_setshow_enum_cmd ("replay-memory-access", no_class,

> @@ -3203,7 +3203,7 @@ When GDB does not support that cpu, this option can be used to enable\n\

>  workarounds for a similar cpu that GDB supports.\n\n\

>  When set to \"none\", errata workarounds are disabled."),

>  		  &set_record_btrace_cpu_cmdlist,

> -		  _("set record btrace cpu "), 1,

> +		  "set record btrace cpu ", 1,

>  		  &set_record_btrace_cmdlist);

>  

>    add_cmd ("auto", class_support, cmd_set_record_btrace_cpu_auto, _("\

> @@ -3219,12 +3219,12 @@ Show the cpu to be used for trace decode."),

>  	   &show_record_btrace_cmdlist);

>  

>    add_prefix_cmd ("bts", class_support, cmd_set_record_btrace_bts,

> -		  _("Set record btrace bts options"),

> +		  _("Set record btrace bts options."),

>  		  &set_record_btrace_bts_cmdlist,

>  		  "set record btrace bts ", 0, &set_record_btrace_cmdlist);

>  

>    add_prefix_cmd ("bts", class_support, cmd_show_record_btrace_bts,

> -		  _("Show record btrace bts options"),

> +		  _("Show record btrace bts options."),

>  		  &show_record_btrace_bts_cmdlist,

>  		  "show record btrace bts ", 0, &show_record_btrace_cmdlist);

>  

> @@ -3243,12 +3243,12 @@ The trace buffer size may not be changed while recording."), NULL,

>  			    &show_record_btrace_bts_cmdlist);

>  

>    add_prefix_cmd ("pt", class_support, cmd_set_record_btrace_pt,

> -		  _("Set record btrace pt options"),

> +		  _("Set record btrace pt options."),

>  		  &set_record_btrace_pt_cmdlist,

>  		  "set record btrace pt ", 0, &set_record_btrace_cmdlist);

>  

>    add_prefix_cmd ("pt", class_support, cmd_show_record_btrace_pt,

> -		  _("Show record btrace pt options"),

> +		  _("Show record btrace pt options."),

>  		  &show_record_btrace_pt_cmdlist,

>  		  "show record btrace pt ", 0, &show_record_btrace_cmdlist);

>  

> diff --git a/gdb/record-full.c b/gdb/record-full.c

> index 95a0353d75..4eb63b19cf 100644

> --- a/gdb/record-full.c

> +++ b/gdb/record-full.c

> @@ -2832,11 +2832,11 @@ Argument is filename.  File must be created with 'record save'."),

>    deprecate_cmd (c, "record full restore");

>  

>    add_prefix_cmd ("full", class_support, set_record_full_command,

> -		  _("Set record options"), &set_record_full_cmdlist,

> +		  _("Set record options."), &set_record_full_cmdlist,

>  		  "set record full ", 0, &set_record_cmdlist);

>  

>    add_prefix_cmd ("full", class_support, show_record_full_command,

> -		  _("Show record options"), &show_record_full_cmdlist,

> +		  _("Show record options."), &show_record_full_cmdlist,

>  		  "show record full ", 0, &show_record_cmdlist);

>  

>    /* Record instructions number limit command.  */

> diff --git a/gdb/record.c b/gdb/record.c

> index 828c19968a..071531db57 100644

> --- a/gdb/record.c

> +++ b/gdb/record.c

> @@ -808,15 +808,15 @@ A size of \"unlimited\" means unlimited lines.  The default is 10."),

>  

>    add_com_alias ("rec", "record", class_obscure, 1);

>    add_prefix_cmd ("record", class_support, set_record_command,

> -		  _("Set record options"), &set_record_cmdlist,

> +		  _("Set record options."), &set_record_cmdlist,

>  		  "set record ", 0, &setlist);

>    add_alias_cmd ("rec", "record", class_obscure, 1, &setlist);

>    add_prefix_cmd ("record", class_support, show_record_command,

> -		  _("Show record options"), &show_record_cmdlist,

> +		  _("Show record options."), &show_record_cmdlist,

>  		  "show record ", 0, &showlist);

>    add_alias_cmd ("rec", "record", class_obscure, 1, &showlist);

>    add_prefix_cmd ("record", class_support, info_record_command,

> -		  _("Info record options"), &info_record_cmdlist,

> +		  _("Info record options."), &info_record_cmdlist,

>  		  "info record ", 0, &infolist);

>    add_alias_cmd ("rec", "record", class_obscure, 1, &infolist);

>  

> diff --git a/gdb/regcache-dump.c b/gdb/regcache-dump.c

> index 1bcf9c3d17..c8ae912284 100644

> --- a/gdb/regcache-dump.c

> +++ b/gdb/regcache-dump.c

> @@ -328,8 +328,8 @@ _initialize_regcache_dump (void)

>  	   &maintenanceprintlist);

>    add_cmd ("remote-registers", class_maintenance,

>  	   maintenance_print_remote_registers, _("\

> -Print the internal register configuration including each register's\n\

> -remote register number and buffer offset in the g/G packets.\n\

> +Print the internal register configuration including remote register number "

> +"and g/G packets offset.\n\

>  Takes an optional file parameter."),

>  	   &maintenanceprintlist);

>  }

> diff --git a/gdb/regcache.c b/gdb/regcache.c

> index 323f0f5ab4..962f00db58 100644

> --- a/gdb/regcache.c

> +++ b/gdb/regcache.c

> @@ -1813,7 +1813,7 @@ _initialize_regcache (void)

>      (regcache::regcache_thread_ptid_changed);

>  

>    add_com ("flushregs", class_maintenance, reg_flush_command,

> -	   _("Force gdb to flush its register cache (maintainer command)"));

> +	   _("Force gdb to flush its register cache (maintainer command)."));

>  

>  #if GDB_SELF_TEST

>    selftests::register_test ("current_regcache", selftests::current_regcache_test);

> diff --git a/gdb/remote.c b/gdb/remote.c

> index 124d254478..24057a7f97 100644

> --- a/gdb/remote.c

> +++ b/gdb/remote.c

> @@ -1825,10 +1825,10 @@ add_packet_config_cmd (struct packet_config *config, const char *name,

>  

>    config->name = name;

>    config->title = title;

> -  set_doc = xstrprintf ("Set use of remote protocol `%s' (%s) packet",

> +  set_doc = xstrprintf ("Set use of remote protocol `%s' (%s) packet.",

>  			name, title);

>    show_doc = xstrprintf ("Show current use of remote "

> -			 "protocol `%s' (%s) packet",

> +			 "protocol `%s' (%s) packet.",

>  			 name, title);

>    /* set/show TITLE-packet {auto,on,off} */

>    cmd_name = xstrprintf ("%s-packet", title);

> @@ -11386,15 +11386,15 @@ init_remote_threadtests (void)

>  {

>    add_com ("tlist", class_obscure, threadlist_test_cmd,

>  	   _("Fetch and print the remote list of "

> -	     "thread identifiers, one pkt only"));

> +	     "thread identifiers, one pkt only."));

>    add_com ("tinfo", class_obscure, threadinfo_test_cmd,

> -	   _("Fetch and display info about one thread"));

> +	   _("Fetch and display info about one thread."));

>    add_com ("tset", class_obscure, threadset_test_cmd,

> -	   _("Test setting to a different thread"));

> +	   _("Test setting to a different thread."));

>    add_com ("tupd", class_obscure, threadlist_update_test_cmd,

> -	   _("Iterate through updating all remote thread info"));

> +	   _("Iterate through updating all remote thread info."));

>    add_com ("talive", class_obscure, threadalive_test,

> -	   _(" Remote thread alive test "));

> +	   _("Remote thread alive test."));

>  }

>  

>  #endif /* 0 */

> @@ -14278,15 +14278,15 @@ _initialize_remote (void)

>    /* set/show remote ...  */

>  

>    add_prefix_cmd ("remote", class_maintenance, set_remote_cmd, _("\

> -Remote protocol specific variables\n\

> +Remote protocol specific variables.\n\

>  Configure various remote-protocol specific variables such as\n\

> -the packets being used"),

> +the packets being used."),

>  		  &remote_set_cmdlist, "set remote ",

>  		  0 /* allow-unknown */, &setlist);

>    add_prefix_cmd ("remote", class_maintenance, show_remote_cmd, _("\

> -Remote protocol specific variables\n\

> +Remote protocol specific variables.\n\

>  Configure various remote-protocol specific variables such as\n\

> -the packets being used"),

> +the packets being used."),

>  		  &remote_show_cmdlist, "show remote ",

>  		  0 /* allow-unknown */, &showlist);

>  

> @@ -14330,8 +14330,8 @@ Valid value is \"Ctrl-C\", \"BREAK\" or \"BREAK-g\". The default is \"Ctrl-C\"."

>  

>    add_setshow_boolean_cmd ("interrupt-on-connect", class_support,

>  			   &interrupt_on_connect, _("\

> -Set whether interrupt-sequence is sent to remote target when gdb connects to."), _("		\

> -Show whether interrupt-sequence is sent to remote target when gdb connects to."), _("		\

> +Set whether interrupt-sequence is sent to remote target when gdb connects to."), _("\

> +Show whether interrupt-sequence is sent to remote target when gdb connects to."), _("\

>  If set, interrupt sequence is sent to remote target."),

>  			   NULL, NULL,

>  			   &remote_set_cmdlist, &remote_show_cmdlist);

> @@ -14699,8 +14699,8 @@ Show the maximum size of the address (in bits) in a memory packet."), NULL,

>       documentation).  */

>    add_setshow_auto_boolean_cmd ("Z-packet", class_obscure,

>  				&remote_Z_packet_detect, _("\

> -Set use of remote protocol `Z' packets"), _("\

> -Show use of remote protocol `Z' packets "), _("\

> +Set use of remote protocol `Z' packets."), _("\

> +Show use of remote protocol `Z' packets."), _("\

>  When set, GDB will attempt to use the remote breakpoint and watchpoint\n\

>  packets."),

>  				set_remote_protocol_Z_packet_cmd,

> @@ -14710,7 +14710,7 @@ packets."),

>  				&remote_set_cmdlist, &remote_show_cmdlist);

>  

>    add_prefix_cmd ("remote", class_files, remote_command, _("\

> -Manipulate files on the remote system\n\

> +Manipulate files on the remote system.\n\

>  Transfer files to and from the remote target system."),

>  		  &remote_cmdlist, "remote ",

>  		  0 /* allow-unknown */, &cmdlist);

> @@ -14729,8 +14729,8 @@ Transfer files to and from the remote target system."),

>  

>    add_setshow_string_noescape_cmd ("exec-file", class_files,

>  				   &remote_exec_file_var, _("\

> -Set the remote pathname for \"run\""), _("\

> -Show the remote pathname for \"run\""), NULL,

> +Set the remote pathname for \"run\"."), _("\

> +Show the remote pathname for \"run\"."), NULL,

>  				   set_remote_exec_file,

>  				   show_remote_exec_file,

>  				   &remote_set_cmdlist,

> diff --git a/gdb/ser-tcp.c b/gdb/ser-tcp.c

> index 5aa7105dc2..fa68656446 100644

> --- a/gdb/ser-tcp.c

> +++ b/gdb/ser-tcp.c

> @@ -480,27 +480,27 @@ _initialize_ser_tcp (void)

>  #endif /* USE_WIN32API */

>  

>    add_prefix_cmd ("tcp", class_maintenance, set_tcp_cmd, _("\

> -TCP protocol specific variables\n\

> -Configure variables specific to remote TCP connections"),

> +TCP protocol specific variables.\n\

> +Configure variables specific to remote TCP connections."),

>  		  &tcp_set_cmdlist, "set tcp ",

>  		  0 /* allow-unknown */, &setlist);

>    add_prefix_cmd ("tcp", class_maintenance, show_tcp_cmd, _("\

> -TCP protocol specific variables\n\

> -Configure variables specific to remote TCP connections"),

> +TCP protocol specific variables.\n\

> +Configure variables specific to remote TCP connections."),

>  		  &tcp_show_cmdlist, "show tcp ",

>  		  0 /* allow-unknown */, &showlist);

>  

>    add_setshow_boolean_cmd ("auto-retry", class_obscure,

>  			   &tcp_auto_retry, _("\

> -Set auto-retry on socket connect"), _("\

> -Show auto-retry on socket connect"), 

> +Set auto-retry on socket connect."), _("\

> +Show auto-retry on socket connect."),

>  			   NULL, NULL, NULL,

>  			   &tcp_set_cmdlist, &tcp_show_cmdlist);

>  

>    add_setshow_uinteger_cmd ("connect-timeout", class_obscure,

>  			    &tcp_retry_limit, _("\

> -Set timeout limit in seconds for socket connection"), _("\

> -Show timeout limit in seconds for socket connection"), _("\

> +Set timeout limit in seconds for socket connection."), _("\

> +Show timeout limit in seconds for socket connection."), _("\

>  If set to \"unlimited\", GDB will keep attempting to establish a\n\

>  connection forever, unless interrupted with Ctrl-c.\n\

>  The default is 15 seconds."),

> diff --git a/gdb/serial.c b/gdb/serial.c

> index bc8d910a5a..a881bbc97c 100644

> --- a/gdb/serial.c

> +++ b/gdb/serial.c

> @@ -706,8 +706,8 @@ using remote targets."),

>  

>    add_setshow_enum_cmd ("parity", no_class, parity_enums,

>                          &parity, _("\

> -Set parity for remote serial I/O"), _("\

> -Show parity for remote serial I/O"), NULL,

> +Set parity for remote serial I/O."), _("\

> +Show parity for remote serial I/O."), NULL,

>                          set_parity,

>                          NULL, /* FIXME: i18n: */

>                          &serial_set_cmdlist, &serial_show_cmdlist);

> @@ -723,8 +723,8 @@ by gdbserver."),

>  

>    add_setshow_enum_cmd ("remotelogbase", no_class, logbase_enums,

>  			&serial_logbase, _("\

> -Set numerical base for remote session logging"), _("\

> -Show numerical base for remote session logging"), NULL,

> +Set numerical base for remote session logging."), _("\

> +Show numerical base for remote session logging."), NULL,

>  			NULL,

>  			NULL, /* FIXME: i18n: */

>  			&setlist, &showlist);

> diff --git a/gdb/skip.c b/gdb/skip.c

> index 127b11dc44..22bb35f995 100644

> --- a/gdb/skip.c

> +++ b/gdb/skip.c

> @@ -696,41 +696,45 @@ If no function name is given, skip the current function."),

>    set_cmd_completer (c, location_completer);

>  

>    c = add_cmd ("enable", class_breakpoint, skip_enable_command, _("\

> -Enable skip entries.  You can specify numbers (e.g. \"skip enable 1 3\"), \

> +Enable skip entries.\n\

> +Usage: skip enable [NUMBER | RANGE]...\n\

> +You can specify numbers (e.g. \"skip enable 1 3\"),\n\

>  ranges (e.g. \"skip enable 4-8\"), or both (e.g. \"skip enable 1 3 4-8\").\n\n\

> -If you don't specify any numbers or ranges, we'll enable all skip entries.\n\n\

> -Usage: skip enable [NUMBER | RANGE]..."),

> +If you don't specify any numbers or ranges, we'll enable all skip entries."),

>  	       &skiplist);

>    set_cmd_completer (c, complete_skip_number);

>  

>    c = add_cmd ("disable", class_breakpoint, skip_disable_command, _("\

> -Disable skip entries.  You can specify numbers (e.g. \"skip disable 1 3\"), \

> +Disable skip entries.\n\

> +Usage: skip disable [NUMBER | RANGE]...\n\

> +You can specify numbers (e.g. \"skip disable 1 3\"),\n\

>  ranges (e.g. \"skip disable 4-8\"), or both (e.g. \"skip disable 1 3 4-8\").\n\n\

> -If you don't specify any numbers or ranges, we'll disable all skip entries.\n\n\

> -Usage: skip disable [NUMBER | RANGE]..."),

> +If you don't specify any numbers or ranges, we'll disable all skip entries."),

>  	       &skiplist);

>    set_cmd_completer (c, complete_skip_number);

>  

>    c = add_cmd ("delete", class_breakpoint, skip_delete_command, _("\

> -Delete skip entries.  You can specify numbers (e.g. \"skip delete 1 3\"), \

> +Delete skip entries.\n\

> +Usage: skip delete [NUMBER | RANGES]...\n\

> +You can specify numbers (e.g. \"skip delete 1 3\"),\n\

>  ranges (e.g. \"skip delete 4-8\"), or both (e.g. \"skip delete 1 3 4-8\").\n\n\

> -If you don't specify any numbers or ranges, we'll delete all skip entries.\n\n\

> -Usage: skip delete [NUMBER | RANGES]..."),

> +If you don't specify any numbers or ranges, we'll delete all skip entries."),

>  	       &skiplist);

>    set_cmd_completer (c, complete_skip_number);

>  

>    add_info ("skip", info_skip_command, _("\

> -Display the status of skips.  You can specify numbers (e.g. \"info skip 1 3\"), \

> +Display the status of skips.\n\

> +Usage: info skip [NUMBER | RANGES]...\n\

> +You can specify numbers (e.g. \"info skip 1 3\"), \n\

>  ranges (e.g. \"info skip 4-8\"), or both (e.g. \"info skip 1 3 4-8\").\n\n\

> -If you don't specify any numbers or ranges, we'll show all skips.\n\n\

> -Usage: info skip [NUMBER | RANGES]..."));

> +If you don't specify any numbers or ranges, we'll show all skips."));

>    set_cmd_completer (c, complete_skip_number);

>  

>    add_setshow_boolean_cmd ("skip", class_maintenance,

>  			   &debug_skip, _("\

>  Set whether to print the debug output about skipping files and functions."),

>  			   _("\

> -Show whether the debug output about skipping files and functions is printed"),

> +Show whether the debug output about skipping files and functions is printed."),

>  			   _("\

>  When non-zero, debug output about skipping files and functions is displayed."),

>  			   NULL, NULL,

> diff --git a/gdb/source.c b/gdb/source.c

> index dec5a2f84b..38bb542492 100644

> --- a/gdb/source.c

> +++ b/gdb/source.c

> @@ -1930,6 +1930,7 @@ A value of \"unlimited\", or zero, means there's no limit."),

>  

>    add_cmd ("substitute-path", class_files, set_substitute_path_command,

>             _("\

> +Add a substitution rule to rewrite source files names directories.\n\

>  Usage: set substitute-path FROM TO\n\

>  Add a substitution rule replacing FROM into TO in source file names.\n\

>  If a substitution rule was previously set for FROM, the old rule\n\

> @@ -1938,6 +1939,7 @@ is replaced by the new one."),

>  

>    add_cmd ("substitute-path", class_files, unset_substitute_path_command,

>             _("\

> +Delete one or all substitution rules rewriting source files names directories.\n\

>  Usage: unset substitute-path [FROM]\n\

>  Delete the rule for substituting FROM in source file names.  If FROM\n\

>  is not specified, all substituting rules are deleted.\n\

> @@ -1946,6 +1948,7 @@ If the debugger cannot find a rule for FROM, it will display a warning."),

>  

>    add_cmd ("substitute-path", class_files, show_substitute_path_command,

>             _("\

> +Show one or all substitution rules rewriting source files names directories.\n\

>  Usage: show substitute-path [FROM]\n\

>  Print the rule for substituting FROM in source file names. If FROM\n\

>  is not specified, print all substitution rules."),

> diff --git a/gdb/stack.c b/gdb/stack.c

> index b3d113d3b4..eb4d5adf15 100644

> --- a/gdb/stack.c

> +++ b/gdb/stack.c

> @@ -110,8 +110,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\

> @@ -123,8 +123,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 */

>    },

>  

> @@ -3299,7 +3299,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);

> @@ -3381,7 +3381,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\

> diff --git a/gdb/symfile.c b/gdb/symfile.c

> index 6f9c81c8b9..29b85195e3 100644

> --- a/gdb/symfile.c

> +++ b/gdb/symfile.c

> @@ -3944,8 +3944,8 @@ that lies within the boundaries of this symbol file in memory."),

>  	       &cmdlist);

>  

>    c = add_cmd ("load", class_files, load_command, _("\

> -Dynamically load FILE into the running program, and record its symbols\n\

> -for access from GDB.\n\

> +Dynamically load FILE into the running program.\n\

> +FILE symbols are recorded for access from GDB.\n\

>  Usage: load [FILE] [OFFSET]\n\

>  An optional load OFFSET may also be given as a literal address.\n\

>  When OFFSET is provided, FILE must also be provided.  FILE can be provided\n\

> diff --git a/gdb/symtab.c b/gdb/symtab.c

> index 4920d94a24..cc97ea1d04 100644

> --- a/gdb/symtab.c

> +++ b/gdb/symtab.c

> @@ -6051,8 +6051,7 @@ Prints the functions.\n"),

>    add_setshow_enum_cmd ("multiple-symbols", no_class,

>                          multiple_symbols_modes, &multiple_symbols_mode,

>                          _("\

> -Set the debugger behavior when more than one symbol are possible matches\n\

> -in an expression."), _("\

> +Set how the debugger handles ambiguities in expressions."), _("\

>  Show how the debugger handles ambiguities in expressions."), _("\

>  Valid values are \"ask\", \"all\", \"cancel\", and the default is \"all\"."),

>                          NULL, NULL, &setlist, &showlist);

> diff --git a/gdb/target-descriptions.c b/gdb/target-descriptions.c

> index bd33091ba9..6805d9e415 100644

> --- a/gdb/target-descriptions.c

> +++ b/gdb/target-descriptions.c

> @@ -1845,8 +1845,8 @@ Unset target description specific variables."),

>    add_setshow_filename_cmd ("filename", class_obscure,

>  			    &tdesc_filename_cmd_string,

>  			    _("\

> -Set the file to read for an XML target description"), _("\

> -Show the file to read for an XML target description"), _("\

> +Set the file to read for an XML target description."), _("\

> +Show the file to read for an XML target description."), _("\

>  When set, GDB will read the target description from a local\n\

>  file instead of querying the remote target."),

>  			    set_tdesc_filename_cmd,

> @@ -1854,8 +1854,8 @@ file instead of querying the remote target."),

>  			    &tdesc_set_cmdlist, &tdesc_show_cmdlist);

>  

>    add_cmd ("filename", class_obscure, unset_tdesc_filename_cmd, _("\

> -Unset the file to read for an XML target description.  When unset,\n\

> -GDB will read the description from the target."),

> +Unset the file to read for an XML target description.\n\

> +When unset, GDB will read the description from the target."),

>  	   &tdesc_unset_cmdlist);

>  

>    add_cmd ("c-tdesc", class_maintenance, maint_print_c_tdesc_cmd, _("\

> @@ -1866,6 +1866,7 @@ Print the current target description as a C source file."),

>  

>    cmd = add_cmd ("xml-descriptions", class_maintenance,

>  		 maintenance_check_xml_descriptions, _("\

> +Check equality of GDB target descriptions and XML created descriptions.\n\

>  Check the target descriptions created in GDB equal the descriptions\n\

>  created from XML files in the directory.\n\

>  The parameter is the directory name."),

> diff --git a/gdb/testsuite/gdb.base/help.exp b/gdb/testsuite/gdb.base/help.exp

> index e65f7c875f..921b3807f6 100644

> --- a/gdb/testsuite/gdb.base/help.exp

> +++ b/gdb/testsuite/gdb.base/help.exp

> @@ -80,7 +80,8 @@ gdb_test "help commands" "Set commands to be executed when the given breakpoints

>  # Test a prefix command.  "delete" is picked at random.

>  # test help delete "d" abbreviation

>  set expected_help_delete {

> -    "Delete some breakpoints or auto-display expressions\.\[\r\n\]+"

> +    "Delete all or some breakpoints or auto-display expressions\.\[\r\n\]+"

> +    "Usage: delete \\\[BREAKPOINTNUM\\\]...\[\r\n\]+"

>      "Arguments are breakpoint numbers with spaces in between\.\[\r\n\]+"

>      "To delete all breakpoints, give no argument\.\[\r\n\]+"

>      "Also a prefix command for deletion of other GDB objects\.\[\r\n\]+"

> @@ -117,8 +118,18 @@ gdb_test "help info bogus-gdb-command" "Undefined info command: \"bogus-gdb-comm

>  gdb_test "help gotcha" "Undefined command: \"gotcha\"\.  Try \"help\"\." "help gotcha"

>  

>  # test apropos regex

> -gdb_test "apropos \\\(print\[\^\[ bsiedf\\\".-\]\\\)" "handle -- Specify how to handle signals"

> +gdb_test "apropos \\\(print\[\^\[ bsiedf\\\".-\]\\\)" "handle -- Specify how to handle signals\."

>  # test apropos >1 word string

> -gdb_test "apropos handle signal" "handle -- Specify how to handle signals"

> +gdb_test "apropos handle signal" "handle -- Specify how to handle signals\."

>  # test apropos apropos

>  gdb_test "apropos apropos" "apropos -- Search for commands matching a REGEXP.*"

> +

> +# Verify the following invariants for the doc help of all commands:

> +#   First line is terminated by a '.' character.

> +#   The last character of the doc is not a new line.

> +# To test this last invariant, GDB apropos command outputs a line

> +# that starts with END_OF_LINE@END_OF_DOC when it finds such

> +# a new line at the end of a help doc.

> +gdb_test_no_output \

> +    "|apropos .| grep -e '\[^\.\]$' -e '^END_OF_LINE@END_OF_DOC '" \

> +    "command help doc first line ends with a dot, doc does not end with eol"

> diff --git a/gdb/testsuite/gdb.base/style.exp b/gdb/testsuite/gdb.base/style.exp

> index a17f201486..5de1ad64c6 100644

> --- a/gdb/testsuite/gdb.base/style.exp

> +++ b/gdb/testsuite/gdb.base/style.exp

> @@ -101,8 +101,8 @@ save_vars { env(TERM) } {

>  	[multi_line \

>  	     "List of classes of commands:" \

>  	     "" \

> -	     "${aliases_expr} -- Aliases of other commands" \

> -	     "${breakpoints_expr} -- Making program stop at certain points" \

> +	     "${aliases_expr} -- Aliases of other commands\." \

> +	     "${breakpoints_expr} -- Making program stop at certain points\." \

>  	     ".*" \

>  	    ] \

>  	"help classes of commands styled with title"

> diff --git a/gdb/top.c b/gdb/top.c

> index 857207c376..bfb4427cc8 100644

> --- a/gdb/top.c

> +++ b/gdb/top.c

> @@ -2109,8 +2109,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);

> @@ -2142,9 +2142,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."),

> @@ -2168,8 +2168,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,

> @@ -2224,7 +2224,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);

> diff --git a/gdb/tracefile-tfile.c b/gdb/tracefile-tfile.c

> index 593556a8ba..4f0c41bce5 100644

> --- a/gdb/tracefile-tfile.c

> +++ b/gdb/tracefile-tfile.c

> @@ -43,7 +43,8 @@

>  static const target_info tfile_target_info = {

>    "tfile",

>    N_("Local trace dump file"),

> -  N_("Use a trace file as a target.  Specify the filename of the trace file.")

> +  N_("Use a trace file as a target.\n\

> +Specify the filename of the trace file.")

>  };

>  

>  class tfile_target final : public tracefile_target

> diff --git a/gdb/tracepoint.c b/gdb/tracepoint.c

> index af5dcd1e33..5a499227e5 100644

> --- a/gdb/tracepoint.c

> +++ b/gdb/tracepoint.c

> @@ -4001,7 +4001,7 @@ _initialize_tracepoint (void)

>    tracepoint_number = -1;

>  

>    add_info ("scope", info_scope_command,

> -	    _("List the variables local to a scope"));

> +	    _("List the variables local to a scope."));

>  

>    add_cmd ("tracepoints", class_trace,

>  	   _("Tracing of program execution without stopping the program."),

> @@ -4031,7 +4031,7 @@ Status of trace state variables and their values."));

>  List target static tracepoints markers."));

>  

>    add_prefix_cmd ("tfind", class_trace, tfind_command, _("\

> -Select a trace frame;\n\

> +Select a trace frame.\n\

>  No argument means forward by one frame; '-' means backward by one frame."),

>  		  &tfindlist, "tfind ", 1, &cmdlist);

>  

> @@ -4132,8 +4132,8 @@ depending on target's capabilities."));

>    default_collect = xstrdup ("");

>    add_setshow_string_cmd ("default-collect", class_trace,

>  			  &default_collect, _("\

> -Set the list of expressions to collect by default"), _("\

> -Show the list of expressions to collect by default"), NULL,

> +Set the list of expressions to collect by default."), _("\

> +Show the list of expressions to collect by default."), NULL,

>  			  NULL, NULL,

>  			  &setlist, &showlist);

>  

> @@ -4173,22 +4173,22 @@ disables any attempt to set the buffer size and lets the target choose."),

>  

>    add_setshow_string_cmd ("trace-user", class_trace,

>  			  &trace_user, _("\

> -Set the user name to use for current and future trace runs"), _("\

> -Show the user name to use for current and future trace runs"), NULL,

> +Set the user name to use for current and future trace runs."), _("\

> +Show the user name to use for current and future trace runs."), NULL,

>  			  set_trace_user, NULL,

>  			  &setlist, &showlist);

>  

>    add_setshow_string_cmd ("trace-notes", class_trace,

>  			  &trace_notes, _("\

> -Set notes string to use for current and future trace runs"), _("\

> -Show the notes string to use for current and future trace runs"), NULL,

> +Set notes string to use for current and future trace runs."), _("\

> +Show the notes string to use for current and future trace runs."), NULL,

>  			  set_trace_notes, NULL,

>  			  &setlist, &showlist);

>  

>    add_setshow_string_cmd ("trace-stop-notes", class_trace,

>  			  &trace_stop_notes, _("\

> -Set notes string to use for future tstop commands"), _("\

> -Show the notes string to use for future tstop commands"), NULL,

> +Set notes string to use for future tstop commands."), _("\

> +Show the notes string to use for future tstop commands."), NULL,

>  			  set_trace_stop_notes, NULL,

>  			  &setlist, &showlist);

>  }

> diff --git a/gdb/tui/tui-win.c b/gdb/tui/tui-win.c

> index 575620f4c8..b1f6fcb8fd 100644

> --- a/gdb/tui/tui-win.c

> +++ b/gdb/tui/tui-win.c

> @@ -1657,11 +1657,11 @@ _initialize_tui_win (void)

>    /* Define the classes of commands.

>       They will appear in the help list in the reverse of this order.  */

>    add_prefix_cmd ("tui", class_tui, set_tui_cmd,

> -                  _("TUI configuration variables"),

> +                  _("TUI configuration variables."),

>  		  &tui_setlist, "set tui ",

>  		  0 /* allow-unknown */, &setlist);

>    add_prefix_cmd ("tui", class_tui, show_tui_cmd,

> -                  _("TUI configuration variables"),

> +                  _("TUI configuration variables."),

>  		  &tui_showlist, "show tui ",

>  		  0 /* allow-unknown */, &showlist);

>  

> @@ -1756,7 +1756,7 @@ This variable controls the attributes to use for the active window border:\n\

>    add_setshow_zuinteger_cmd ("tab-width", no_class,

>  			     &internal_tab_width, _("\

>  Set the tab width, in characters, for the TUI."), _("\

> -Show the tab witdh, in characters, for the TUI"), _("\

> +Show the tab witdh, in characters, for the TUI."), _("\

>  This variable controls how many spaces are used to display a tab character."),

>  			     tui_set_tab_width, tui_show_tab_width,

>  			     &tui_setlist, &tui_showlist);

> diff --git a/gdb/utils.c b/gdb/utils.c

> index f55661287e..88450cccba 100644

> --- a/gdb/utils.c

> +++ b/gdb/utils.c

> @@ -530,10 +530,10 @@ add_internal_problem_command (struct internal_problem *problem)

>    if (problem->user_settable_should_quit)

>      {

>        set_doc = xstrprintf (_("Set whether GDB should quit "

> -			      "when an %s is detected"),

> +			      "when an %s is detected."),

>  			    problem->name);

>        show_doc = xstrprintf (_("Show whether GDB will quit "

> -			       "when an %s is detected"),

> +			       "when an %s is detected."),

>  			     problem->name);

>        add_setshow_enum_cmd ("quit", class_maintenance,

>  			    internal_problem_modes,

> @@ -553,10 +553,10 @@ add_internal_problem_command (struct internal_problem *problem)

>    if (problem->user_settable_should_dump_core)

>      {

>        set_doc = xstrprintf (_("Set whether GDB should create a core "

> -			      "file of GDB when %s is detected"),

> +			      "file of GDB when %s is detected."),

>  			    problem->name);

>        show_doc = xstrprintf (_("Show whether GDB will create a core "

> -			       "file of GDB when %s is detected"),

> +			       "file of GDB when %s is detected."),

>  			     problem->name);

>        add_setshow_enum_cmd ("corefile", class_maintenance,

>  			    internal_problem_modes,

> diff --git a/gdb/valprint.c b/gdb/valprint.c

> index 6f9b47da80..0a4cc8e971 100644

> --- a/gdb/valprint.c

> +++ b/gdb/valprint.c

> @@ -3140,7 +3140,7 @@ static const gdb::option::option_def value_print_option_defs[] = {

>      [] (value_print_options *opt) { return &opt->print_array_indexes; },

>      show_print_array_indexes, /* show_cmd_cb */

>      N_("Set printing of array indexes."),

> -    N_("Show printing of array indexes"),

> +    N_("Show printing of array indexes."),

>      NULL, /* help_doc */

>    },

>
Tom Tromey July 10, 2019, 5:02 p.m. | #2
>>>>> "Philippe" == Philippe Waroquiers <philippe.waroquiers@skynet.be> writes:


Philippe> With this patch, the help docs now respect 2 invariants:
Philippe>   * The first line of a command help is terminated by a '.' character.
Philippe>   * The last character of a command help is not a newline character.

Thanks for doing this.  I'm in favor of the change, as I think it
improves the help experience and doesn't make anything worse.

Philippe> gdb/ChangeLog
Philippe> 2019-06-16  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

Philippe> 	* cli/cli-decode.h (print_doc_line): Add for_value_prefix argument.
Philippe> 	* cli/cli-decode.c (print_doc_line): Likewise.  It now prints
Philippe> 	the full first line, except when FOR_VALUE_PREFIX.  In this case,
Philippe> 	the trailing '.' is not output, and the first character is uppercased.
Philippe> 	(print_help_for_command): Update call to print_doc_line.
Philippe> 	(print_doc_of_command): Likewise.  Output a specific string
Philippe> 	when doc string ends with a line feed to allow the testsuite
Philippe> 	to detect the broken invariant.
Philippe> 	* cli/cli-setshow.c (deprecated_show_value_hack): Likewise.
Philippe> 	* cli/cli-option.c (append_indented_doc): Do not append newline.
Philippe> 	(build_help_option): Append newline after first appended_indented_doc
Philippe> 	only if a second call is done.
Philippe> 	(build_help): Append 2 new lines before each option, except the first
Philippe> 	one.
Philippe> 	* compile/compile.c (_initialize_compile): Add new lines after
Philippe> 	%OPTIONS%, when not at the end of the help.
Philippe> C	hange help doc or code

Little hiccup in the ChangeLog.

Philippe> +  /* Checks that the documentation does not help with a new line.
Philippe> +     If it does, output a special marker string that gdb.base/help.exp
Philippe> +     will detect.  */
Philippe> +  if (c->doc[strlen (c->doc) - 1] == '\n')
Philippe> +    fprintf_filtered (stream, "END_OF_LINE@END_OF_DOC %s%s\n",
Philippe> +		      prefix, c->name);

I think this can't be an assertion, because user commands could hit it,
and that seems too harsh; but could it be a unit test?  That might be
better than printing something magic, especially since IIUC the user can
end up seeing this stuff.

Philippe> -Usage: maintenance selftest [filter]\n\
Philippe> +Usage: maintenance selftest [FILTER]\n\

Thank you.

Philippe> +gdb_test_no_output \
Philippe> +    "|apropos .| grep -e '\[^\.\]$' -e '^END_OF_LINE@END_OF_DOC '" \
Philippe> +    "command help doc first line ends with a dot, doc does not end with eol"

I'm not sure we can rely on having grep in the test suite.  If you
switch the patch to a self-test, then this is moot; otherwise, is this
used elsewhere?  I think a different approach is to write to a log file
and then examine it with Tcl.  I believe some other tests do this.

Tom
Philippe Waroquiers July 10, 2019, 10:31 p.m. | #3
On Wed, 2019-07-10 at 11:02 -0600, Tom Tromey wrote:
> Philippe> +  /* Checks that the documentation does not help with a new line.

> Philippe> +     If it does, output a special marker string that gdb.base/help.exp

> Philippe> +     will detect.  */

> Philippe> +  if (c->doc[strlen (c->doc) - 1] == '\n')

> Philippe> +    fprintf_filtered (stream, "END_OF_LINE@END_OF_DOC %s%s\n",

> Philippe> +		      prefix, c->name);

> 

> I think this can't be an assertion, because user commands could hit it,

> and that seems too harsh; but could it be a unit test?  That might be

> better than printing something magic, especially since IIUC the user can

> end up seeing this stuff.

Effectively, the user can end up seeing this, but only if the GDB test
was not run and/or was not fixed.


> Philippe> +gdb_test_no_output \

> Philippe> +    "|apropos .| grep -e '\[^\.\]$' -e '^END_OF_LINE@END_OF_DOC '" \

> Philippe> +    "command help doc first line ends with a dot, doc does not end with eol"

> 

> I'm not sure we can rely on having grep in the test suite.  If you

> switch the patch to a self-test, then this is moot; otherwise, is this

> used elsewhere?  I think a different approach is to write to a log file

> and then examine it with Tcl.  I believe some other tests do this.

The testsuite uses various unix commands such as mv/touch/grep/stty/...
But maybe these tests are all failing e.g. on windows ?

In any case, I will see if it is easy to do a selftest instead,
without duplicating too much of e.g. the recursive traversal of the commands,
maybe by adding a 'for_self_test' boolean arg to apropos_command ...

Thanks for the comments,

Philippe
Tom Tromey July 11, 2019, 12:22 p.m. | #4
>>>>> "Philippe" == Philippe Waroquiers <philippe.waroquiers@skynet.be> writes:


>> I think this can't be an assertion, because user commands could hit it,

>> and that seems too harsh; but could it be a unit test?  That might be

>> better than printing something magic, especially since IIUC the user can

>> end up seeing this stuff.


Philippe> Effectively, the user can end up seeing this, but only if the GDB test
Philippe> was not run and/or was not fixed.

Or if there is any command written in Python or Guile that has a newline
at the end of its help text.  These commands can be supplied any number
of ways.

Tom
Pedro Alves July 11, 2019, 12:53 p.m. | #5
On 7/11/19 1:22 PM, Tom Tromey wrote:
>>>>>> "Philippe" == Philippe Waroquiers <philippe.waroquiers@skynet.be> writes:

> 

>>> I think this can't be an assertion, because user commands could hit it,

>>> and that seems too harsh; but could it be a unit test?  That might be

>>> better than printing something magic, especially since IIUC the user can

>>> end up seeing this stuff.

> 

> Philippe> Effectively, the user can end up seeing this, but only if the GDB test

> Philippe> was not run and/or was not fixed.

> 

> Or if there is any command written in Python or Guile that has a newline

> at the end of its help text.  These commands can be supplied any number

> of ways.


Could this be a warning at command-registration-time instead?  That
way you would see if as soon as the command is registered.  And it'd
be hard to introduce a regression with build-in commands since
everyone would start seeing a warning.

Thanks,
Pedro Alves
Tom Tromey July 11, 2019, 1:12 p.m. | #6
>>>>> "Pedro" == Pedro Alves <palves@redhat.com> writes:


Pedro> On 7/11/19 1:22 PM, Tom Tromey wrote:
>>>>>>> "Philippe" == Philippe Waroquiers <philippe.waroquiers@skynet.be> writes:

>> 

>>>> I think this can't be an assertion, because user commands could hit it,

>>>> and that seems too harsh; but could it be a unit test?  That might be

>>>> better than printing something magic, especially since IIUC the user can

>>>> end up seeing this stuff.

>> 

Philippe> Effectively, the user can end up seeing this, but only if the GDB test
Philippe> was not run and/or was not fixed.
>> 

>> Or if there is any command written in Python or Guile that has a newline

>> at the end of its help text.  These commands can be supplied any number

>> of ways.


Pedro> Could this be a warning at command-registration-time instead?  That
Pedro> way you would see if as soon as the command is registered.  And it'd
Pedro> be hard to introduce a regression with build-in commands since
Pedro> everyone would start seeing a warning.

Where I was coming from is that this is a pretty minor cosmetic issue;
and while it makes sense for gdb to follow this rule, it isn't worth it
for 3rd party commands.  So, we should test gdb itself to avoid problems
here, but ignore problems coming from elsewhere.

I don't feel super strongly about it.

Tom
Pedro Alves July 11, 2019, 1:49 p.m. | #7
On 6/16/19 8:58 PM, Philippe Waroquiers wrote:
> @@ -448,8 +448,8 @@ _initialize_interpreter (void)

>    c = add_cmd ("interpreter-exec", class_support,

>  	       interpreter_exec_cmd, _("\

>  Execute a command in an interpreter.\n\

> -It takes two arguments:\n\

> +Usage: interpreter-exec INTERPRETER COMMAND...\n\

>  The first argument is the name of the interpreter to use.\n\

> -The second argument is the command to execute."), &cmdlist);

> +The following arguments are the commands to execute."), &cmdlist);


This sentence is incorrect -- there's only one command to execute.
You meant to say that it's the command to execute and its arguments.
As it was before was also correct, IMHO.

>    set_cmd_completer (c, interpreter_completer);

>  }


Thanks,
Pedro Alves
Pedro Alves July 11, 2019, 2:18 p.m. | #8
On 6/16/19 8:58 PM, Philippe Waroquiers wrote:
>    add_cmd ("substitute-path", class_files, set_substitute_path_command,

>             _("\

> +Add a substitution rule to rewrite source files names directories.\n\


"files names directories" reads a bit ood, seems like a plural too many
somewhere.

Maybe you're missing a possessive apostrophe, like:

Add a substitution rule to rewrite source files names' directories.


>  Usage: set substitute-path FROM TO\n\

>  Add a substitution rule replacing FROM into TO in source file names.\n\


This sentence here looks a little redundant now.

>  If a substitution rule was previously set for FROM, the old rule\n\

> @@ -1938,6 +1939,7 @@ is replaced by the new one."),

>  

>    add_cmd ("substitute-path", class_files, unset_substitute_path_command,

>             _("\

> +Delete one or all substitution rules rewriting source files names directories.\n\


Ditto.

>  Usage: unset substitute-path [FROM]\n\



-- 
Thanks,
Pedro Alves
Pedro Alves July 11, 2019, 3:38 p.m. | #9
On 6/16/19 8:58 PM, Philippe Waroquiers wrote:
>    add_prefix_cmd ("delete", class_breakpoint, delete_command, _("\

> -Delete some breakpoints or auto-display expressions.\n\

> +Delete all or some breakpoints or auto-display expressions.\n\


I think this "or auto-display expressions" part should be removed,
since "delete NUM" does not delete displays -- "delete display" does.

I see no reason for "apropos display" to show "delete", for example.

> +Usage: delete [BREAKPOINTNUM]...\n\

>  Arguments are breakpoint numbers with spaces in between.\n\

>  To delete all breakpoints, give no argument.\n\


Thanks,
Pedro Alves
Pedro Alves July 11, 2019, 3:43 p.m. | #10
On 6/16/19 8:58 PM, Philippe Waroquiers wrote:
> 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.


Can you split these parts of the patch from the validation parts?
I.e., let's get the help fixes out of the way first.  The validation
parts can be discussed separately, and it's easier to distinguish
them if they're not mixed up with the rest.

Thanks,
Pedro Alves
Pedro Alves July 11, 2019, 3:44 p.m. | #11
On 7/10/19 6:02 PM, Tom Tromey wrote:
> Philippe> +  /* Checks that the documentation does not help with a new line.


"does not END with a new line", I suppose.

Thanks,
Pedro Alves
Pedro Alves July 11, 2019, 3:49 p.m. | #12
On 7/11/19 2:12 PM, Tom Tromey wrote:
>>>>>> "Pedro" == Pedro Alves <palves@redhat.com> writes:

> 

> Pedro> On 7/11/19 1:22 PM, Tom Tromey wrote:

>>>>>>>> "Philippe" == Philippe Waroquiers <philippe.waroquiers@skynet.be> writes:

>>>

>>>>> I think this can't be an assertion, because user commands could hit it,

>>>>> and that seems too harsh; but could it be a unit test?  That might be

>>>>> better than printing something magic, especially since IIUC the user can

>>>>> end up seeing this stuff.

>>>

> Philippe> Effectively, the user can end up seeing this, but only if the GDB test

> Philippe> was not run and/or was not fixed.

>>>

>>> Or if there is any command written in Python or Guile that has a newline

>>> at the end of its help text.  These commands can be supplied any number

>>> of ways.

> 

> Pedro> Could this be a warning at command-registration-time instead?  That

> Pedro> way you would see if as soon as the command is registered.  And it'd

> Pedro> be hard to introduce a regression with build-in commands since

> Pedro> everyone would start seeing a warning.

> 

> Where I was coming from is that this is a pretty minor cosmetic issue;

> and while it makes sense for gdb to follow this rule, it isn't worth it

> for 3rd party commands.  So, we should test gdb itself to avoid problems

> here, but ignore problems coming from elsewhere.

> 

> I don't feel super strongly about it.


I agree that it's not desirable to include the extra markup in the
help output of 3rd party commands.  That seems too harsh since it shows
up on every invocation and is certainly distracting for the user.

I kind of assumed that the markup also catches bad uses of the '.',
which affects proper integration with "apropos".  If it's just for
the end line, then it's less of a deal.

My view was that that a warning is much less invasive than changing the
help text, since a warning would show (usually) at gdb startup when some
script is loaded, where users already get some text they need to
scroll over.

We could also make it a gdb_assert in the add_cmd functions,
and then make the python layer strip away any trailing whitespace.

Thanks,
Pedro Alves
Pedro Alves July 11, 2019, 3:51 p.m. | #13
On 7/11/19 4:49 PM, Pedro Alves wrote:
> We could also make it a gdb_assert in the add_cmd functions,

> and then make the python layer strip away any trailing whitespace.


I think this is my preferred solution, btw.  Makes it unnecessary to
add any testing infrastructure, and makes python do the right thing
automatically.

Thanks,
Pedro Alves
Tom Tromey July 11, 2019, 3:58 p.m. | #14
>>>>> "Pedro" == Pedro Alves <palves@redhat.com> writes:


Pedro> On 7/11/19 4:49 PM, Pedro Alves wrote:
>> We could also make it a gdb_assert in the add_cmd functions,

>> and then make the python layer strip away any trailing whitespace.


Pedro> I think this is my preferred solution, btw.  Makes it unnecessary to
Pedro> add any testing infrastructure, and makes python do the right thing
Pedro> automatically.

Sounds like a reasonable plan.

Tom
Philippe Waroquiers July 29, 2019, 9:27 p.m. | #15
On Thu, 2019-07-11 at 14:49 +0100, Pedro Alves wrote:
> On 6/16/19 8:58 PM, Philippe Waroquiers wrote:

> > @@ -448,8 +448,8 @@ _initialize_interpreter (void)

> >    c = add_cmd ("interpreter-exec", class_support,

> >  	       interpreter_exec_cmd, _("\

> >  Execute a command in an interpreter.\n\

> > -It takes two arguments:\n\

> > +Usage: interpreter-exec INTERPRETER COMMAND...\n\

> >  The first argument is the name of the interpreter to use.\n\

> > -The second argument is the command to execute."), &cmdlist);

> > +The following arguments are the commands to execute."), &cmdlist);

> 

> This sentence is incorrect -- there's only one command to execute.


The code loops over a set of strings,
and execute each of these strings.

When trying:
(gdb) interpreter-exec console bt bt
#0  0x00007ffff78fe603 in select () at ../sysdeps/unix/syscall-template.S:84
#1  0x0000555555554f5e in sleeper_or_burner (v=0x7fffffffdf30) at sleepers.c:86
#2  0x000055555555549d in main (argc=1, argv=0x7fffffffe0b8) at sleepers.c:194
#0  0x00007ffff78fe603 in select () at ../sysdeps/unix/syscall-template.S:84
#1  0x0000555555554f5e in sleeper_or_burner (v=0x7fffffffdf30) at sleepers.c:86
#2  0x000055555555549d in main (argc=1, argv=0x7fffffffe0b8) at sleepers.c:194
(gdb)

Now, I have to admit that at least for the console interpreter, unclear where
the syntax for the arguments is described.

Looks like the below works:
(gdb) interpreter-exec console bt\ 1 bt\ 2
#0  0x00007ffff78fe603 in select () at ../sysdeps/unix/syscall-template.S:84
(More stack frames follow...)
#0  0x00007ffff78fe603 in select () at ../sysdeps/unix/syscall-template.S:84
#1  0x0000555555554f5e in sleeper_or_burner (v=0x7fffffffdf30) at sleepers.c:86
(More stack frames follow...)
(gdb) 

This also works:
(gdb) interpreter-exec console "bt 1" "bt 2"
#0  0x00007ffff78fe603 in select () at ../sysdeps/unix/syscall-template.S:84
(More stack frames follow...)
#0  0x00007ffff78fe603 in select () at ../sysdeps/unix/syscall-template.S:84
#1  0x0000555555554f5e in sleeper_or_burner (v=0x7fffffffdf30) at sleepers.c:86
(More stack frames follow...)
(gdb) 


So, it looks like really several commands can be given, but I am not sure
if the commands and argument syntax is the same for all interpreters.

Also, when looking at some mi documentation, we again see only one command
mentionned:
The '-interpreter-exec' Command
-------------------------------

Synopsis
--------

     -interpreter-exec INTERPRETER COMMAND

   Execute the specified COMMAND in the given INTERPRETER.



> You meant to say that it's the command to execute and its arguments.

> As it was before was also correct, IMHO.

> 

> >    set_cmd_completer (c, interpreter_completer);

> >  }

> 

> Thanks,

> Pedro Alves

Patch

diff --git a/gdb/ada-lang.c b/gdb/ada-lang.c
index 1b5f18316f..c6c702459d 100644
--- a/gdb/ada-lang.c
+++ b/gdb/ada-lang.c
@@ -14380,7 +14380,7 @@  _initialize_ada_language (void)
   initialize_ada_catchpoint_ops ();
 
   add_prefix_cmd ("ada", no_class, set_ada_command,
-                  _("Prefix command for changing Ada-specific settings"),
+                  _("Prefix command for changing Ada-specific settings."),
                   &set_ada_list, "set ada ", 0, &setlist);
 
   add_prefix_cmd ("ada", no_class, show_ada_command,
@@ -14389,8 +14389,8 @@  _initialize_ada_language (void)
 
   add_setshow_boolean_cmd ("trust-PAD-over-XVS", class_obscure,
                            &trust_pad_over_xvs, _("\
-Enable or disable an optimization trusting PAD types over XVS types"), _("\
-Show whether an optimization trusting PAD types over XVS types is activated"),
+Enable or disable an optimization trusting PAD types over XVS types."), _("\
+Show whether an optimization trusting PAD types over XVS types is activated."),
                            _("\
 This is related to the encoding used by the GNAT compiler.  The debugger\n\
 should normally trust the contents of PAD types, but certain older versions\n\
@@ -14404,9 +14404,9 @@  this option to \"off\" unless necessary."),
   add_setshow_boolean_cmd ("print-signatures", class_vars,
 			   &print_signatures, _("\
 Enable or disable the output of formal and return types for functions in the \
-overloads selection menu"), _("\
+overloads selection menu."), _("\
 Show whether the output of formal and return types for functions in the \
-overloads selection menu is activated"),
+overloads selection menu is activated."),
 			   NULL, NULL, NULL, &set_ada_list, &show_ada_list);
 
   add_catch_command ("exception", _("\
@@ -14468,7 +14468,7 @@  the regular expression are listed."));
                   0/*allow-unknown*/, &maintenance_set_cmdlist);
 
   add_prefix_cmd ("ada", class_maintenance, maint_show_ada_cmd,
-		  _("Show Ada maintenance-related variables"),
+		  _("Show Ada maintenance-related variables."),
                   &maint_show_ada_cmdlist, "maintenance show ada ",
                   0/*allow-unknown*/, &maintenance_show_cmdlist);
 
diff --git a/gdb/ada-tasks.c b/gdb/ada-tasks.c
index 9c07f0ca22..f34b5b81e7 100644
--- a/gdb/ada-tasks.c
+++ b/gdb/ada-tasks.c
@@ -1413,9 +1413,9 @@  _initialize_tasks (void)
 
   /* Some new commands provided by this module.  */
   add_info ("tasks", info_tasks_command,
-            _("Provide information about all known Ada tasks"));
+            _("Provide information about all known Ada tasks."));
   add_cmd ("task", class_run, task_command,
            _("Use this command to switch between Ada tasks.\n\
-Without argument, this command simply prints the current task ID"),
+Without argument, this command simply prints the current task ID."),
            &cmdlist);
 }
diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
index ccd778b7a1..8e5a0d3dc4 100644
--- a/gdb/breakpoint.c
+++ b/gdb/breakpoint.c
@@ -15483,7 +15483,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\
@@ -15493,46 +15494,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."),
@@ -15541,7 +15550,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\
@@ -15549,7 +15559,8 @@  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 or auto-display expressions.\n\
+Usage: delete [BREAKPOINTNUM]...\n\
 Arguments are breakpoint numbers with spaces in between.\n\
 To delete all breakpoints, give no argument.\n\
 \n\
@@ -15560,7 +15571,8 @@  The \"unset\" command is also an alias for \"delete\"."),
   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\"."),
@@ -15837,15 +15849,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);
 
@@ -15946,16 +15958,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);
 
@@ -15970,8 +15982,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;
 
diff --git a/gdb/cli/cli-cmds.c b/gdb/cli/cli-cmds.c
index 62f4d7f0c5..5a17673f71 100644
--- a/gdb/cli/cli-cmds.c
+++ b/gdb/cli/cli-cmds.c
@@ -1769,7 +1769,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\
@@ -1881,11 +1882,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, _("\
@@ -1984,7 +1985,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 a6ddd8cc6d..21d2a7b1f6 100644
--- a/gdb/cli/cli-decode.c
+++ b/gdb/cli/cli-decode.c
@@ -978,8 +978,15 @@  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);
+
+  /* Checks that the documentation does not help with a new line.
+     If it does, output a special marker string that gdb.base/help.exp
+     will detect.  */
+  if (c->doc[strlen (c->doc) - 1] == '\n')
+    fprintf_filtered (stream, "END_OF_LINE@END_OF_DOC %s%s\n",
+		      prefix, c->name);
 }
 
 /* Recursively walk the commandlist structures, and print out the
@@ -1217,9 +1224,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 +1240,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 +1251,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 +1276,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 05280d9d22..b72970b635 100644
--- a/gdb/cli/cli-decode.h
+++ b/gdb/cli/cli-decode.h
@@ -257,9 +257,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 a8b9955c57..9e39be197b 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 9a53ec0592..96243c9ec6 100644
--- a/gdb/cli/cli-option.c
+++ b/gdb/cli/cli-option.c
@@ -611,7 +611,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
@@ -640,8 +639,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);
+	}
     }
 }
 
@@ -651,6 +652,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%");
@@ -658,7 +660,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 8199fa7c0b..b68ce99200 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 fb6486bfdf..e594e38cd6 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."));
diff --git a/gdb/compile/compile.c b/gdb/compile/compile.c
index 25d0bfe602..f82af8679c 100644
--- a/gdb/compile/compile.c
+++ b/gdb/compile/compile.c
@@ -978,6 +978,7 @@  Usage: compile code [OPTION]... [CODE]\n\
 \n\
 Options:\n\
 %OPTIONS%\n\
+\n\
 The source code may be specified as a simple one line expression, e.g.:\n\
 \n\
     compile code printf(\"Hello world\\n\");\n\
@@ -1017,7 +1018,8 @@  Evaluate EXPR by using the compiler and print result.\n\
 Usage: compile print [[OPTION]... --] [/FMT] [EXPR]\n\
 \n\
 Options:\n\
-%OPTIONS%\
+%OPTIONS%\n\
+\n\
 Note: because this command accepts arbitrary expressions, if you\n\
 specify any command option, you must use a double dash (\"--\")\n\
 to mark the end of option processing.  E.g.: \"compile print -o -- myobj\".\n\
@@ -1049,8 +1051,8 @@  When on, compile command debugging is enabled."),
 
   add_setshow_string_cmd ("compile-args", class_support,
 			  &compile_args,
-			  _("Set compile command GCC command-line arguments"),
-			  _("Show compile command GCC command-line arguments"),
+			  _("Set compile command GCC command-line arguments."),
+			  _("Show compile command GCC command-line arguments."),
 			  _("\
 Use options like -I (include file directory) or ABI settings.\n\
 String quoting is parsed like in shell, for example:\n\
@@ -1078,9 +1080,9 @@  String quoting is parsed like in shell, for example:\n\
   add_setshow_optional_filename_cmd ("compile-gcc", class_support,
 				     &compile_gcc,
 				     _("Set compile command "
-				       "GCC driver filename"),
+				       "GCC driver filename."),
 				     _("Show compile command "
-				       "GCC driver filename"),
+				       "GCC driver filename."),
 				     _("\
 It should be absolute filename of the gcc executable.\n\
 If empty the default target triplet will be searched in $PATH."),
diff --git a/gdb/corelow.c b/gdb/corelow.c
index 9fcc2d2372..511fea81fa 100644
--- a/gdb/corelow.c
+++ b/gdb/corelow.c
@@ -56,7 +56,8 @@  static core_fns *sniff_core_bfd (gdbarch *core_gdbarch,
 static const target_info core_target_info = {
   "core",
   N_("Local core dump file"),
-  N_("Use a core file as a target.  Specify the filename of the core file.")
+  N_("Use a core file as a target.\n\
+Specify the filename of the core file.")
 };
 
 class core_target final : public process_stratum_target
diff --git a/gdb/dwarf-index-cache.c b/gdb/dwarf-index-cache.c
index 7222f0528d..a036f5b207 100644
--- a/gdb/dwarf-index-cache.c
+++ b/gdb/dwarf-index-cache.c
@@ -317,12 +317,12 @@  _initialize_index_cache ()
 
   /* set index-cache */
   add_prefix_cmd ("index-cache", class_files, set_index_cache_command,
-		  _("Set index-cache options"), &set_index_cache_prefix_list,
+		  _("Set index-cache options."), &set_index_cache_prefix_list,
 		  "set index-cache ", false, &setlist);
 
   /* show index-cache */
   add_prefix_cmd ("index-cache", class_files, show_index_cache_command,
-		  _("Show index-cache options"), &show_index_cache_prefix_list,
+		  _("Show index-cache options."), &show_index_cache_prefix_list,
 		  "show index-cache ", false, &showlist);
 
   /* set index-cache on */
diff --git a/gdb/dwarf2read.c b/gdb/dwarf2read.c
index 4cf9fcfa21..49cd1e8a62 100644
--- a/gdb/dwarf2read.c
+++ b/gdb/dwarf2read.c
@@ -25794,13 +25794,13 @@  _initialize_dwarf2_read (void)
 {
   add_prefix_cmd ("dwarf", class_maintenance, set_dwarf_cmd, _("\
 Set DWARF specific variables.\n\
-Configure DWARF variables such as the cache size"),
+Configure DWARF variables such as the cache size."),
                   &set_dwarf_cmdlist, "maintenance set dwarf ",
                   0/*allow-unknown*/, &maintenance_set_cmdlist);
 
   add_prefix_cmd ("dwarf", class_maintenance, show_dwarf_cmd, _("\
-Show DWARF specific variables\n\
-Show DWARF variables such as the cache size"),
+Show DWARF specific variables.\n\
+Show DWARF variables such as the cache size."),
                   &show_dwarf_cmdlist, "maintenance show dwarf ",
                   0/*allow-unknown*/, &maintenance_show_cmdlist);
 
diff --git a/gdb/filesystem.c b/gdb/filesystem.c
index fdc4713007..a942e7067d 100644
--- a/gdb/filesystem.c
+++ b/gdb/filesystem.c
@@ -83,8 +83,8 @@  _initialize_filesystem (void)
 			class_files,
 			target_file_system_kinds,
 			&target_file_system_kind, _("\
-Set assumed file system kind for target reported file names"), _("\
-Show assumed file system kind for target reported file names"),
+Set assumed file system kind for target reported file names."), _("\
+Show assumed file system kind for target reported file names."),
 			_("\
 If `unix', target file names (e.g., loaded shared library file names)\n\
 starting the forward slash (`/') character are considered absolute,\n\
diff --git a/gdb/frame.c b/gdb/frame.c
index 84e0397db9..adac24f68c 100644
--- a/gdb/frame.c
+++ b/gdb/frame.c
@@ -2949,8 +2949,8 @@  Configure backtrace variables such as the backtrace limit"),
 		  &set_backtrace_cmdlist, "set backtrace ",
 		  0/*allow-unknown*/, &setlist);
   add_prefix_cmd ("backtrace", class_maintenance, show_backtrace_cmd, _("\
-Show backtrace specific variables\n\
-Show backtrace variables such as the backtrace limit"),
+Show backtrace specific variables.\n\
+Show backtrace variables such as the backtrace limit."),
 		  &show_backtrace_cmdlist, "show backtrace ",
 		  0/*allow-unknown*/, &showlist);
 
diff --git a/gdb/gnu-nat.c b/gdb/gnu-nat.c
index 5eeac9270a..5692ac5132 100644
--- a/gdb/gnu-nat.c
+++ b/gdb/gnu-nat.c
@@ -3312,15 +3312,15 @@  This is the same as setting `task pause', `exceptions', and\n\
 
   /* Commands to show information about the task's ports.  */
   add_info ("send-rights", info_send_rights_cmd,
-	    _("Show information about the task's send rights"));
+	    _("Show information about the task's send rights."));
   add_info ("receive-rights", info_recv_rights_cmd,
-	    _("Show information about the task's receive rights"));
+	    _("Show information about the task's receive rights."));
   add_info ("port-rights", info_port_rights_cmd,
-	    _("Show information about the task's port rights"));
+	    _("Show information about the task's port rights."));
   add_info ("port-sets", info_port_sets_cmd,
-	    _("Show information about the task's port sets"));
+	    _("Show information about the task's port sets."));
   add_info ("dead-names", info_dead_names_cmd,
-	    _("Show information about the task's dead names"));
+	    _("Show information about the task's dead names."));
   add_info_alias ("ports", "port-rights", 1);
   add_info_alias ("port", "port-rights", 1);
   add_info_alias ("psets", "port-sets", 1);
diff --git a/gdb/infcall.c b/gdb/infcall.c
index 84092d37e6..be99673f67 100644
--- a/gdb/infcall.c
+++ b/gdb/infcall.c
@@ -1388,7 +1388,7 @@  will result in an error."),
   add_setshow_boolean_cmd ("coerce-float-to-double", class_obscure,
 			   &coerce_float_to_double_p, _("\
 Set coercion of floats to doubles when calling functions."), _("\
-Show coercion of floats to doubles when calling functions"), _("\
+Show coercion of floats to doubles when calling functions."), _("\
 Variables of type float should generally be converted to doubles before\n\
 calling an unprototyped function, and left alone when calling a prototyped\n\
 function.  However, some older debug info formats do not provide enough\n\
diff --git a/gdb/infcmd.c b/gdb/infcmd.c
index afd7bb5a54..5361f1c000 100644
--- a/gdb/infcmd.c
+++ b/gdb/infcmd.c
@@ -3319,6 +3319,7 @@  reason)."));
   add_com_alias ("s", "step", class_run, 1);
 
   c = add_com ("until", class_run, until_command, _("\
+Execute until past the current line or past a LOCATION.\n\
 Execute until the program reaches a source line greater than the current\n\
 or a specified location (same args as break command) within the current \
 frame."));
@@ -3394,10 +3395,10 @@  in the named register groups."));
 	    _("Execution status of the program."));
 
   add_info ("float", info_float_command,
-	    _("Print the status of the floating point unit"));
+	    _("Print the status of the floating point unit."));
 
   add_info ("vector", info_vector_command,
-	    _("Print the status of the vector unit"));
+	    _("Print the status of the vector unit."));
 
   add_prefix_cmd ("proc", class_info, info_proc_cmd,
 		  _("\
diff --git a/gdb/interps.c b/gdb/interps.c
index 363502e767..f2f137ca91 100644
--- a/gdb/interps.c
+++ b/gdb/interps.c
@@ -378,7 +378,7 @@  interpreter_exec_cmd (const char *args, int from_tty)
   nrules = prules.count ();
 
   if (nrules < 2)
-    error (_("Usage: interpreter-exec INTERPRETER [ COMMAND... ]"));
+    error (_("Usage: interpreter-exec INTERPRETER COMMAND..."));
 
   old_interp = ui_interp->current_interpreter;
 
@@ -448,8 +448,8 @@  _initialize_interpreter (void)
   c = add_cmd ("interpreter-exec", class_support,
 	       interpreter_exec_cmd, _("\
 Execute a command in an interpreter.\n\
-It takes two arguments:\n\
+Usage: interpreter-exec INTERPRETER COMMAND...\n\
 The first argument is the name of the interpreter to use.\n\
-The second argument is the command to execute."), &cmdlist);
+The following arguments are the commands to execute."), &cmdlist);
   set_cmd_completer (c, interpreter_completer);
 }
diff --git a/gdb/language.c b/gdb/language.c
index a7c09ccd6d..de3b59cb72 100644
--- a/gdb/language.c
+++ b/gdb/language.c
@@ -1172,16 +1172,16 @@  _initialize_language (void)
 
   add_setshow_enum_cmd ("range", class_support, type_or_range_names,
 			&range,
-			_("Set range checking.  (on/warn/off/auto)"),
-			_("Show range checking.  (on/warn/off/auto)"),
+			_("Set range checking (on/warn/off/auto)."),
+			_("Show range checking (on/warn/off/auto)."),
 			NULL, set_range_command,
 			show_range_command,
 			&setchecklist, &showchecklist);
 
   add_setshow_enum_cmd ("case-sensitive", class_support, case_sensitive_names,
 			&case_sensitive, _("\
-Set case sensitivity in name search.  (on/off/auto)"), _("\
-Show case sensitivity in name search.  (on/off/auto)"), _("\
+Set case sensitivity in name search (on/off/auto)."), _("\
+Show case sensitivity in name search (on/off/auto)."), _("\
 For Fortran the default is off; for other languages the default is on."),
 			set_case_command,
 			show_case_command,
diff --git a/gdb/linux-fork.c b/gdb/linux-fork.c
index d323a716e3..160ddb6cbc 100644
--- a/gdb/linux-fork.c
+++ b/gdb/linux-fork.c
@@ -765,7 +765,8 @@  Fork a duplicate process (experimental)."));
      process.  */
 
   add_com ("restart", class_obscure, restart_command, _("\
-restart N: restore program context from a checkpoint.\n\
+Restore program context from a checkpoint.\n\
+Usage: restart N\n\
 Argument N is checkpoint ID, as displayed by 'info checkpoints'."));
 
   /* Delete checkpoint command: kill the process and remove it from
diff --git a/gdb/maint-test-options.c b/gdb/maint-test-options.c
index 599155cbfe..c70a321b8a 100644
--- a/gdb/maint-test-options.c
+++ b/gdb/maint-test-options.c
@@ -398,8 +398,8 @@  Command used for testing options processing.\n\
 Usage: maint test-options require-delimiter [[OPTION]... --] [OPERAND]...\n\
 \n\
 Options:\n\
-\n\
 %OPTIONS%\n\
+\n\
 If you specify any command option, you must use a double dash (\"--\")\n\
 to mark the end of option processing."),
 			       def_group);
@@ -410,7 +410,6 @@  Command used for testing options processing.\n\
 Usage: maint test-options unknown-is-error [OPTION]... [OPERAND]...\n\
 \n\
 Options:\n\
-\n\
 %OPTIONS%"),
 			       def_group);
 
@@ -420,7 +419,6 @@  Command used for testing options processing.\n\
 Usage: maint test-options unknown-is-operand [OPTION]... [OPERAND]...\n\
 \n\
 Options:\n\
-\n\
 %OPTIONS%"),
 			       def_group);
 
diff --git a/gdb/maint-test-settings.c b/gdb/maint-test-settings.c
index fa13519eb9..e339761bec 100644
--- a/gdb/maint-test-settings.c
+++ b/gdb/maint-test-settings.c
@@ -133,8 +133,8 @@  Show GDB internal variables used for set/show command infrastructure testing."),
 
   add_setshow_boolean_cmd ("boolean", class_maintenance,
 			   &maintenance_test_settings_boolean, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
 			   nullptr, /* help_doc */
 			   nullptr, /* set_cmd */
 			   maintenance_test_settings_show_value_cmd,
@@ -143,8 +143,8 @@  command used for internal testing"),
 
   add_setshow_auto_boolean_cmd ("auto-boolean", class_maintenance,
 				&maintenance_test_settings_auto_boolean, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
 				nullptr, /* help_doc */
 				nullptr, /* set_cmd */
 				maintenance_test_settings_show_value_cmd,
@@ -153,8 +153,8 @@  command used for internal testing"),
 
   add_setshow_uinteger_cmd ("uinteger", class_maintenance,
 			   &maintenance_test_settings_uinteger, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
 			   nullptr, /* help_doc */
 			   nullptr, /* set_cmd */
 			   maintenance_test_settings_show_value_cmd,
@@ -163,8 +163,8 @@  command used for internal testing"),
 
   add_setshow_integer_cmd ("integer", class_maintenance,
 			   &maintenance_test_settings_integer, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
 			   nullptr, /* help_doc */
 			   nullptr, /* set_cmd */
 			   maintenance_test_settings_show_value_cmd,
@@ -173,8 +173,8 @@  command used for internal testing"),
 
   add_setshow_string_cmd ("string", class_maintenance,
      &maintenance_test_settings_string, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
      nullptr, /* help_doc */
      nullptr, /* set_cmd */
      maintenance_test_settings_show_value_cmd,
@@ -184,8 +184,8 @@  command used for internal testing"),
   add_setshow_string_noescape_cmd
     ("string-noescape", class_maintenance,
      &maintenance_test_settings_string_noescape, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
      nullptr, /* help_doc */
      nullptr, /* set_cmd */
      maintenance_test_settings_show_value_cmd,
@@ -195,8 +195,8 @@  command used for internal testing"),
   add_setshow_optional_filename_cmd
     ("optional-filename", class_maintenance,
      &maintenance_test_settings_optional_filename, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
      nullptr, /* help_doc */
      nullptr, /* set_cmd */
      maintenance_test_settings_show_value_cmd,
@@ -205,8 +205,8 @@  command used for internal testing"),
 
   add_setshow_filename_cmd ("filename", class_maintenance,
 			    &maintenance_test_settings_filename, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
 			    nullptr, /* help_doc */
 			    nullptr, /* set_cmd */
 			    maintenance_test_settings_show_value_cmd,
@@ -215,8 +215,8 @@  command used for internal testing"),
 
   add_setshow_zinteger_cmd ("zinteger", class_maintenance,
 			    &maintenance_test_settings_zinteger, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
 			    nullptr, /* help_doc */
 			    nullptr, /* set_cmd */
 			    maintenance_test_settings_show_value_cmd,
@@ -225,8 +225,8 @@  command used for internal testing"),
 
   add_setshow_zuinteger_cmd ("zuinteger", class_maintenance,
 			     &maintenance_test_settings_zuinteger, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
 			     nullptr, /* help_doc */
 			     nullptr, /* set_cmd */
 			     maintenance_test_settings_show_value_cmd,
@@ -236,8 +236,8 @@  command used for internal testing"),
   add_setshow_zuinteger_unlimited_cmd
     ("zuinteger-unlimited", class_maintenance,
      &maintenance_test_settings_zuinteger_unlimited, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
      nullptr, /* help_doc */
      nullptr, /* set_cmd */
      maintenance_test_settings_show_value_cmd,
@@ -247,8 +247,8 @@  command used for internal testing"),
   add_setshow_enum_cmd ("enum", class_maintenance,
 			maintenance_test_settings_enums,
 			&maintenance_test_settings_enum, _("\
-command used for internal testing"), _("\
-command used for internal testing"),
+command used for internal testing."), _("\
+command used for internal testing."),
 			nullptr, /* help_doc */
 			nullptr, /* set_cmd */
 			maintenance_test_settings_show_value_cmd,
diff --git a/gdb/maint.c b/gdb/maint.c
index aaabb35224..12e0e36ea9 100644
--- a/gdb/maint.c
+++ b/gdb/maint.c
@@ -993,7 +993,7 @@  Commands for showing internal info about the program being debugged."),
   add_alias_cmd ("i", "info", class_maintenance, 1, &maintenancelist);
 
   add_cmd ("sections", class_maintenance, maintenance_info_sections, _("\
-List the BFD sections of the exec and core files. \n\
+List the BFD sections of the exec and core files.\n\
 Arguments may be any combination of:\n\
 	[one or more section names]\n\
 	ALLOC LOAD RELOC READONLY CODE DATA ROM CONSTRUCTOR\n\
@@ -1137,21 +1137,22 @@  Commands for checking internal gdb state."),
 	   &maintenancelist);
 
   add_cmd ("deprecate", class_maintenance, maintenance_deprecate, _("\
-Deprecate a command.  Note that this is just in here so the \n\
-testsuite can check the command deprecator. You probably shouldn't use this,\n\
-rather you should use the C function deprecate_cmd().  If you decide you \n\
-want to use it: maintenance deprecate 'commandname' \"replacement\". The \n\
-replacement is optional."), &maintenancelist);
+Deprecate a command (for testing purposes).\n\
+Usage: maintenance deprecate COMMANDNAME [\"REPLACEMENT\"]\n\
+This is used by the testsuite to check the command deprecator.\n\
+You probably shouldn't use this,\n\
+rather you should use the C function deprecate_cmd()."), &maintenancelist);
 
   add_cmd ("undeprecate", class_maintenance, maintenance_undeprecate, _("\
-Undeprecate a command.  Note that this is just in here so the \n\
-testsuite can check the command deprecator. You probably shouldn't use this,\n\
-If you decide you want to use it: maintenance undeprecate 'commandname'"),
+Undeprecate a command (for testing purposes).\n\
+Usage: maintenance undeprecate COMMANDNAME\n\
+This is used by the testsuite to check the command deprecator.\n\
+You probably shouldn't use this."),
 	   &maintenancelist);
 
   add_cmd ("selftest", class_maintenance, maintenance_selftest, _("\
 Run gdb's unit tests.\n\
-Usage: maintenance selftest [filter]\n\
+Usage: maintenance selftest [FILTER]\n\
 This will run any unit tests that were built in to gdb.\n\
 If a filter is given, only the tests with that value in their name will ran."),
 	   &maintenancelist);
diff --git a/gdb/memattr.c b/gdb/memattr.c
index 858a41abfb..cf819866b8 100644
--- a/gdb/memattr.c
+++ b/gdb/memattr.c
@@ -598,8 +598,8 @@  void
 _initialize_mem (void)
 {
   add_com ("mem", class_vars, mem_command, _("\
-Define attributes for memory region or reset memory region handling to\n\
-target-based.\n\
+Define attributes for memory region or reset memory region handling to "
+"target-based.\n\
 Usage: mem auto\n\
        mem LOW HIGH [MODE WIDTH CACHE],\n\
 where MODE  may be rw (read/write), ro (read-only) or wo (write-only),\n\
@@ -625,14 +625,14 @@  Usage: delete mem [ID]...\n\
 Do \"info mem\" to see current list of IDs."), &deletelist);
 
   add_info ("mem", info_mem_command,
-	    _("Memory region attributes"));
+	    _("Memory region attributes."));
 
   add_prefix_cmd ("mem", class_vars, dummy_cmd, _("\
-Memory regions settings"),
+Memory regions settings."),
 		  &mem_set_cmdlist, "set mem ",
 		  0/* allow-unknown */, &setlist);
   add_prefix_cmd ("mem", class_vars, dummy_cmd, _("\
-Memory regions settings"),
+Memory regions settings."),
 		  &mem_show_cmdlist, "show mem  ",
 		  0/* allow-unknown */, &showlist);
 
diff --git a/gdb/printcmd.c b/gdb/printcmd.c
index 0509360581..5a61615c70 100644
--- a/gdb/printcmd.c
+++ b/gdb/printcmd.c
@@ -2751,7 +2751,7 @@  Usage: output EXP\n\
 This is useful in user-defined commands."));
 
   add_prefix_cmd ("set", class_vars, set_command, _("\
-Evaluate expression EXP and assign result to variable VAR\n\
+Evaluate expression EXP and assign result to variable VAR.\n\
 Usage: set VAR = EXP\n\
 This uses assignment syntax appropriate for the current language\n\
 (VAR = EXP or VAR := EXP for example).\n\
@@ -2765,7 +2765,7 @@  You can see these environment settings with the \"show\" command."),
 		  &setlist, "set ", 1, &cmdlist);
   if (dbx_commands)
     add_com ("assign", class_vars, set_command, _("\
-Evaluate expression EXP and assign result to variable VAR\n\
+Evaluate expression EXP and assign result to variable VAR.\n\
 Usage: assign VAR = EXP\n\
 This uses assignment syntax appropriate for the current language\n\
 (VAR = EXP or VAR := EXP for example).\n\
@@ -2786,7 +2786,7 @@  history, if it is not void."));
   set_cmd_completer_handle_brkchars (c, print_command_completer);
 
   add_cmd ("variable", class_vars, set_command, _("\
-Evaluate expression EXP and assign result to variable VAR\n\
+Evaluate expression EXP and assign result to variable VAR.\n\
 Usage: set variable VAR = EXP\n\
 This uses assignment syntax appropriate for the current language\n\
 (VAR = EXP or VAR := EXP for example).\n\
@@ -2804,7 +2804,8 @@  Print value of expression EXP.\n\
 Usage: print [[OPTION]... --] [/FMT] [EXP]\n\
 \n\
 Options:\n\
-%OPTIONS%\
+%OPTIONS%\n\
+\n\
 Note: because this command accepts arbitrary expressions, if you\n\
 specify any command option, you must use a double dash (\"--\")\n\
 to mark the end of option processing.  E.g.: \"print -o -- myobj\".\n\
diff --git a/gdb/python/lib/gdb/function/strfns.py b/gdb/python/lib/gdb/function/strfns.py
index d29ff61d6c..c56957bdb2 100644
--- a/gdb/python/lib/gdb/function/strfns.py
+++ b/gdb/python/lib/gdb/function/strfns.py
@@ -21,7 +21,7 @@  import re
 
 
 class _MemEq(gdb.Function):
-  """$_memeq - compare bytes of memory
+  """$_memeq - compare bytes of memory.
 
 Usage: $_memeq (A, B, LEN)
 
@@ -44,7 +44,7 @@  Returns:
 
 
 class _StrLen(gdb.Function):
-  """$_strlen - compute string length
+  """$_strlen - compute string length.
 
 Usage: $_strlen (A)
 
@@ -59,7 +59,7 @@  Returns:
 
 
 class _StrEq(gdb.Function):
-  """$_streq - check string equality
+  """$_streq - check string equality.
 
 Usage: $_streq (A, B)
 
@@ -77,7 +77,7 @@  Example (amd64-linux):
 
 
 class _RegEx(gdb.Function):
-  """$_regex - check if a string matches a regular expression
+  """$_regex - check if a string matches a regular expression.
 
 Usage: $_regex (STRING, REGEX)
 
diff --git a/gdb/ravenscar-thread.c b/gdb/ravenscar-thread.c
index 6636a89554..f217d949f6 100644
--- a/gdb/ravenscar-thread.c
+++ b/gdb/ravenscar-thread.c
@@ -601,17 +601,17 @@  _initialize_ravenscar ()
   gdb::observers::inferior_created.attach (ravenscar_inferior_created);
 
   add_prefix_cmd ("ravenscar", no_class, set_ravenscar_command,
-                  _("Prefix command for changing Ravenscar-specific settings"),
+                  _("Prefix command for changing Ravenscar-specific settings."),
                   &set_ravenscar_list, "set ravenscar ", 0, &setlist);
 
   add_prefix_cmd ("ravenscar", no_class, show_ravenscar_command,
-                  _("Prefix command for showing Ravenscar-specific settings"),
+                  _("Prefix command for showing Ravenscar-specific settings."),
                   &show_ravenscar_list, "show ravenscar ", 0, &showlist);
 
   add_setshow_boolean_cmd ("task-switching", class_obscure,
                            &ravenscar_task_support, _("\
-Enable or disable support for GNAT Ravenscar tasks"), _("\
-Show whether support for GNAT Ravenscar tasks is enabled"),
+Enable or disable support for GNAT Ravenscar tasks."), _("\
+Show whether support for GNAT Ravenscar tasks is enabled."),
                            _("\
 Enable or disable support for task/thread switching with the GNAT\n\
 Ravenscar run-time library for bareboard configuration."),
diff --git a/gdb/record-btrace.c b/gdb/record-btrace.c
index 21085d5c62..a2a1e9c6dd 100644
--- a/gdb/record-btrace.c
+++ b/gdb/record-btrace.c
@@ -3170,11 +3170,11 @@  This format may not be available on all processors."),
   add_alias_cmd ("pt", "btrace pt", class_obscure, 1, &record_cmdlist);
 
   add_prefix_cmd ("btrace", class_support, cmd_set_record_btrace,
-		  _("Set record options"), &set_record_btrace_cmdlist,
+		  _("Set record options."), &set_record_btrace_cmdlist,
 		  "set record btrace ", 0, &set_record_cmdlist);
 
   add_prefix_cmd ("btrace", class_support, cmd_show_record_btrace,
-		  _("Show record options"), &show_record_btrace_cmdlist,
+		  _("Show record options."), &show_record_btrace_cmdlist,
 		  "show record btrace ", 0, &show_record_cmdlist);
 
   add_setshow_enum_cmd ("replay-memory-access", no_class,
@@ -3203,7 +3203,7 @@  When GDB does not support that cpu, this option can be used to enable\n\
 workarounds for a similar cpu that GDB supports.\n\n\
 When set to \"none\", errata workarounds are disabled."),
 		  &set_record_btrace_cpu_cmdlist,
-		  _("set record btrace cpu "), 1,
+		  "set record btrace cpu ", 1,
 		  &set_record_btrace_cmdlist);
 
   add_cmd ("auto", class_support, cmd_set_record_btrace_cpu_auto, _("\
@@ -3219,12 +3219,12 @@  Show the cpu to be used for trace decode."),
 	   &show_record_btrace_cmdlist);
 
   add_prefix_cmd ("bts", class_support, cmd_set_record_btrace_bts,
-		  _("Set record btrace bts options"),
+		  _("Set record btrace bts options."),
 		  &set_record_btrace_bts_cmdlist,
 		  "set record btrace bts ", 0, &set_record_btrace_cmdlist);
 
   add_prefix_cmd ("bts", class_support, cmd_show_record_btrace_bts,
-		  _("Show record btrace bts options"),
+		  _("Show record btrace bts options."),
 		  &show_record_btrace_bts_cmdlist,
 		  "show record btrace bts ", 0, &show_record_btrace_cmdlist);
 
@@ -3243,12 +3243,12 @@  The trace buffer size may not be changed while recording."), NULL,
 			    &show_record_btrace_bts_cmdlist);
 
   add_prefix_cmd ("pt", class_support, cmd_set_record_btrace_pt,
-		  _("Set record btrace pt options"),
+		  _("Set record btrace pt options."),
 		  &set_record_btrace_pt_cmdlist,
 		  "set record btrace pt ", 0, &set_record_btrace_cmdlist);
 
   add_prefix_cmd ("pt", class_support, cmd_show_record_btrace_pt,
-		  _("Show record btrace pt options"),
+		  _("Show record btrace pt options."),
 		  &show_record_btrace_pt_cmdlist,
 		  "show record btrace pt ", 0, &show_record_btrace_cmdlist);
 
diff --git a/gdb/record-full.c b/gdb/record-full.c
index 95a0353d75..4eb63b19cf 100644
--- a/gdb/record-full.c
+++ b/gdb/record-full.c
@@ -2832,11 +2832,11 @@  Argument is filename.  File must be created with 'record save'."),
   deprecate_cmd (c, "record full restore");
 
   add_prefix_cmd ("full", class_support, set_record_full_command,
-		  _("Set record options"), &set_record_full_cmdlist,
+		  _("Set record options."), &set_record_full_cmdlist,
 		  "set record full ", 0, &set_record_cmdlist);
 
   add_prefix_cmd ("full", class_support, show_record_full_command,
-		  _("Show record options"), &show_record_full_cmdlist,
+		  _("Show record options."), &show_record_full_cmdlist,
 		  "show record full ", 0, &show_record_cmdlist);
 
   /* Record instructions number limit command.  */
diff --git a/gdb/record.c b/gdb/record.c
index 828c19968a..071531db57 100644
--- a/gdb/record.c
+++ b/gdb/record.c
@@ -808,15 +808,15 @@  A size of \"unlimited\" means unlimited lines.  The default is 10."),
 
   add_com_alias ("rec", "record", class_obscure, 1);
   add_prefix_cmd ("record", class_support, set_record_command,
-		  _("Set record options"), &set_record_cmdlist,
+		  _("Set record options."), &set_record_cmdlist,
 		  "set record ", 0, &setlist);
   add_alias_cmd ("rec", "record", class_obscure, 1, &setlist);
   add_prefix_cmd ("record", class_support, show_record_command,
-		  _("Show record options"), &show_record_cmdlist,
+		  _("Show record options."), &show_record_cmdlist,
 		  "show record ", 0, &showlist);
   add_alias_cmd ("rec", "record", class_obscure, 1, &showlist);
   add_prefix_cmd ("record", class_support, info_record_command,
-		  _("Info record options"), &info_record_cmdlist,
+		  _("Info record options."), &info_record_cmdlist,
 		  "info record ", 0, &infolist);
   add_alias_cmd ("rec", "record", class_obscure, 1, &infolist);
 
diff --git a/gdb/regcache-dump.c b/gdb/regcache-dump.c
index 1bcf9c3d17..c8ae912284 100644
--- a/gdb/regcache-dump.c
+++ b/gdb/regcache-dump.c
@@ -328,8 +328,8 @@  _initialize_regcache_dump (void)
 	   &maintenanceprintlist);
   add_cmd ("remote-registers", class_maintenance,
 	   maintenance_print_remote_registers, _("\
-Print the internal register configuration including each register's\n\
-remote register number and buffer offset in the g/G packets.\n\
+Print the internal register configuration including remote register number "
+"and g/G packets offset.\n\
 Takes an optional file parameter."),
 	   &maintenanceprintlist);
 }
diff --git a/gdb/regcache.c b/gdb/regcache.c
index 323f0f5ab4..962f00db58 100644
--- a/gdb/regcache.c
+++ b/gdb/regcache.c
@@ -1813,7 +1813,7 @@  _initialize_regcache (void)
     (regcache::regcache_thread_ptid_changed);
 
   add_com ("flushregs", class_maintenance, reg_flush_command,
-	   _("Force gdb to flush its register cache (maintainer command)"));
+	   _("Force gdb to flush its register cache (maintainer command)."));
 
 #if GDB_SELF_TEST
   selftests::register_test ("current_regcache", selftests::current_regcache_test);
diff --git a/gdb/remote.c b/gdb/remote.c
index 124d254478..24057a7f97 100644
--- a/gdb/remote.c
+++ b/gdb/remote.c
@@ -1825,10 +1825,10 @@  add_packet_config_cmd (struct packet_config *config, const char *name,
 
   config->name = name;
   config->title = title;
-  set_doc = xstrprintf ("Set use of remote protocol `%s' (%s) packet",
+  set_doc = xstrprintf ("Set use of remote protocol `%s' (%s) packet.",
 			name, title);
   show_doc = xstrprintf ("Show current use of remote "
-			 "protocol `%s' (%s) packet",
+			 "protocol `%s' (%s) packet.",
 			 name, title);
   /* set/show TITLE-packet {auto,on,off} */
   cmd_name = xstrprintf ("%s-packet", title);
@@ -11386,15 +11386,15 @@  init_remote_threadtests (void)
 {
   add_com ("tlist", class_obscure, threadlist_test_cmd,
 	   _("Fetch and print the remote list of "
-	     "thread identifiers, one pkt only"));
+	     "thread identifiers, one pkt only."));
   add_com ("tinfo", class_obscure, threadinfo_test_cmd,
-	   _("Fetch and display info about one thread"));
+	   _("Fetch and display info about one thread."));
   add_com ("tset", class_obscure, threadset_test_cmd,
-	   _("Test setting to a different thread"));
+	   _("Test setting to a different thread."));
   add_com ("tupd", class_obscure, threadlist_update_test_cmd,
-	   _("Iterate through updating all remote thread info"));
+	   _("Iterate through updating all remote thread info."));
   add_com ("talive", class_obscure, threadalive_test,
-	   _(" Remote thread alive test "));
+	   _("Remote thread alive test."));
 }
 
 #endif /* 0 */
@@ -14278,15 +14278,15 @@  _initialize_remote (void)
   /* set/show remote ...  */
 
   add_prefix_cmd ("remote", class_maintenance, set_remote_cmd, _("\
-Remote protocol specific variables\n\
+Remote protocol specific variables.\n\
 Configure various remote-protocol specific variables such as\n\
-the packets being used"),
+the packets being used."),
 		  &remote_set_cmdlist, "set remote ",
 		  0 /* allow-unknown */, &setlist);
   add_prefix_cmd ("remote", class_maintenance, show_remote_cmd, _("\
-Remote protocol specific variables\n\
+Remote protocol specific variables.\n\
 Configure various remote-protocol specific variables such as\n\
-the packets being used"),
+the packets being used."),
 		  &remote_show_cmdlist, "show remote ",
 		  0 /* allow-unknown */, &showlist);
 
@@ -14330,8 +14330,8 @@  Valid value is \"Ctrl-C\", \"BREAK\" or \"BREAK-g\". The default is \"Ctrl-C\"."
 
   add_setshow_boolean_cmd ("interrupt-on-connect", class_support,
 			   &interrupt_on_connect, _("\
-Set whether interrupt-sequence is sent to remote target when gdb connects to."), _("		\
-Show whether interrupt-sequence is sent to remote target when gdb connects to."), _("		\
+Set whether interrupt-sequence is sent to remote target when gdb connects to."), _("\
+Show whether interrupt-sequence is sent to remote target when gdb connects to."), _("\
 If set, interrupt sequence is sent to remote target."),
 			   NULL, NULL,
 			   &remote_set_cmdlist, &remote_show_cmdlist);
@@ -14699,8 +14699,8 @@  Show the maximum size of the address (in bits) in a memory packet."), NULL,
      documentation).  */
   add_setshow_auto_boolean_cmd ("Z-packet", class_obscure,
 				&remote_Z_packet_detect, _("\
-Set use of remote protocol `Z' packets"), _("\
-Show use of remote protocol `Z' packets "), _("\
+Set use of remote protocol `Z' packets."), _("\
+Show use of remote protocol `Z' packets."), _("\
 When set, GDB will attempt to use the remote breakpoint and watchpoint\n\
 packets."),
 				set_remote_protocol_Z_packet_cmd,
@@ -14710,7 +14710,7 @@  packets."),
 				&remote_set_cmdlist, &remote_show_cmdlist);
 
   add_prefix_cmd ("remote", class_files, remote_command, _("\
-Manipulate files on the remote system\n\
+Manipulate files on the remote system.\n\
 Transfer files to and from the remote target system."),
 		  &remote_cmdlist, "remote ",
 		  0 /* allow-unknown */, &cmdlist);
@@ -14729,8 +14729,8 @@  Transfer files to and from the remote target system."),
 
   add_setshow_string_noescape_cmd ("exec-file", class_files,
 				   &remote_exec_file_var, _("\
-Set the remote pathname for \"run\""), _("\
-Show the remote pathname for \"run\""), NULL,
+Set the remote pathname for \"run\"."), _("\
+Show the remote pathname for \"run\"."), NULL,
 				   set_remote_exec_file,
 				   show_remote_exec_file,
 				   &remote_set_cmdlist,
diff --git a/gdb/ser-tcp.c b/gdb/ser-tcp.c
index 5aa7105dc2..fa68656446 100644
--- a/gdb/ser-tcp.c
+++ b/gdb/ser-tcp.c
@@ -480,27 +480,27 @@  _initialize_ser_tcp (void)
 #endif /* USE_WIN32API */
 
   add_prefix_cmd ("tcp", class_maintenance, set_tcp_cmd, _("\
-TCP protocol specific variables\n\
-Configure variables specific to remote TCP connections"),
+TCP protocol specific variables.\n\
+Configure variables specific to remote TCP connections."),
 		  &tcp_set_cmdlist, "set tcp ",
 		  0 /* allow-unknown */, &setlist);
   add_prefix_cmd ("tcp", class_maintenance, show_tcp_cmd, _("\
-TCP protocol specific variables\n\
-Configure variables specific to remote TCP connections"),
+TCP protocol specific variables.\n\
+Configure variables specific to remote TCP connections."),
 		  &tcp_show_cmdlist, "show tcp ",
 		  0 /* allow-unknown */, &showlist);
 
   add_setshow_boolean_cmd ("auto-retry", class_obscure,
 			   &tcp_auto_retry, _("\
-Set auto-retry on socket connect"), _("\
-Show auto-retry on socket connect"), 
+Set auto-retry on socket connect."), _("\
+Show auto-retry on socket connect."),
 			   NULL, NULL, NULL,
 			   &tcp_set_cmdlist, &tcp_show_cmdlist);
 
   add_setshow_uinteger_cmd ("connect-timeout", class_obscure,
 			    &tcp_retry_limit, _("\
-Set timeout limit in seconds for socket connection"), _("\
-Show timeout limit in seconds for socket connection"), _("\
+Set timeout limit in seconds for socket connection."), _("\
+Show timeout limit in seconds for socket connection."), _("\
 If set to \"unlimited\", GDB will keep attempting to establish a\n\
 connection forever, unless interrupted with Ctrl-c.\n\
 The default is 15 seconds."),
diff --git a/gdb/serial.c b/gdb/serial.c
index bc8d910a5a..a881bbc97c 100644
--- a/gdb/serial.c
+++ b/gdb/serial.c
@@ -706,8 +706,8 @@  using remote targets."),
 
   add_setshow_enum_cmd ("parity", no_class, parity_enums,
                         &parity, _("\
-Set parity for remote serial I/O"), _("\
-Show parity for remote serial I/O"), NULL,
+Set parity for remote serial I/O."), _("\
+Show parity for remote serial I/O."), NULL,
                         set_parity,
                         NULL, /* FIXME: i18n: */
                         &serial_set_cmdlist, &serial_show_cmdlist);
@@ -723,8 +723,8 @@  by gdbserver."),
 
   add_setshow_enum_cmd ("remotelogbase", no_class, logbase_enums,
 			&serial_logbase, _("\
-Set numerical base for remote session logging"), _("\
-Show numerical base for remote session logging"), NULL,
+Set numerical base for remote session logging."), _("\
+Show numerical base for remote session logging."), NULL,
 			NULL,
 			NULL, /* FIXME: i18n: */
 			&setlist, &showlist);
diff --git a/gdb/skip.c b/gdb/skip.c
index 127b11dc44..22bb35f995 100644
--- a/gdb/skip.c
+++ b/gdb/skip.c
@@ -696,41 +696,45 @@  If no function name is given, skip the current function."),
   set_cmd_completer (c, location_completer);
 
   c = add_cmd ("enable", class_breakpoint, skip_enable_command, _("\
-Enable skip entries.  You can specify numbers (e.g. \"skip enable 1 3\"), \
+Enable skip entries.\n\
+Usage: skip enable [NUMBER | RANGE]...\n\
+You can specify numbers (e.g. \"skip enable 1 3\"),\n\
 ranges (e.g. \"skip enable 4-8\"), or both (e.g. \"skip enable 1 3 4-8\").\n\n\
-If you don't specify any numbers or ranges, we'll enable all skip entries.\n\n\
-Usage: skip enable [NUMBER | RANGE]..."),
+If you don't specify any numbers or ranges, we'll enable all skip entries."),
 	       &skiplist);
   set_cmd_completer (c, complete_skip_number);
 
   c = add_cmd ("disable", class_breakpoint, skip_disable_command, _("\
-Disable skip entries.  You can specify numbers (e.g. \"skip disable 1 3\"), \
+Disable skip entries.\n\
+Usage: skip disable [NUMBER | RANGE]...\n\
+You can specify numbers (e.g. \"skip disable 1 3\"),\n\
 ranges (e.g. \"skip disable 4-8\"), or both (e.g. \"skip disable 1 3 4-8\").\n\n\
-If you don't specify any numbers or ranges, we'll disable all skip entries.\n\n\
-Usage: skip disable [NUMBER | RANGE]..."),
+If you don't specify any numbers or ranges, we'll disable all skip entries."),
 	       &skiplist);
   set_cmd_completer (c, complete_skip_number);
 
   c = add_cmd ("delete", class_breakpoint, skip_delete_command, _("\
-Delete skip entries.  You can specify numbers (e.g. \"skip delete 1 3\"), \
+Delete skip entries.\n\
+Usage: skip delete [NUMBER | RANGES]...\n\
+You can specify numbers (e.g. \"skip delete 1 3\"),\n\
 ranges (e.g. \"skip delete 4-8\"), or both (e.g. \"skip delete 1 3 4-8\").\n\n\
-If you don't specify any numbers or ranges, we'll delete all skip entries.\n\n\
-Usage: skip delete [NUMBER | RANGES]..."),
+If you don't specify any numbers or ranges, we'll delete all skip entries."),
 	       &skiplist);
   set_cmd_completer (c, complete_skip_number);
 
   add_info ("skip", info_skip_command, _("\
-Display the status of skips.  You can specify numbers (e.g. \"info skip 1 3\"), \
+Display the status of skips.\n\
+Usage: info skip [NUMBER | RANGES]...\n\
+You can specify numbers (e.g. \"info skip 1 3\"), \n\
 ranges (e.g. \"info skip 4-8\"), or both (e.g. \"info skip 1 3 4-8\").\n\n\
-If you don't specify any numbers or ranges, we'll show all skips.\n\n\
-Usage: info skip [NUMBER | RANGES]..."));
+If you don't specify any numbers or ranges, we'll show all skips."));
   set_cmd_completer (c, complete_skip_number);
 
   add_setshow_boolean_cmd ("skip", class_maintenance,
 			   &debug_skip, _("\
 Set whether to print the debug output about skipping files and functions."),
 			   _("\
-Show whether the debug output about skipping files and functions is printed"),
+Show whether the debug output about skipping files and functions is printed."),
 			   _("\
 When non-zero, debug output about skipping files and functions is displayed."),
 			   NULL, NULL,
diff --git a/gdb/source.c b/gdb/source.c
index dec5a2f84b..38bb542492 100644
--- a/gdb/source.c
+++ b/gdb/source.c
@@ -1930,6 +1930,7 @@  A value of \"unlimited\", or zero, means there's no limit."),
 
   add_cmd ("substitute-path", class_files, set_substitute_path_command,
            _("\
+Add a substitution rule to rewrite source files names directories.\n\
 Usage: set substitute-path FROM TO\n\
 Add a substitution rule replacing FROM into TO in source file names.\n\
 If a substitution rule was previously set for FROM, the old rule\n\
@@ -1938,6 +1939,7 @@  is replaced by the new one."),
 
   add_cmd ("substitute-path", class_files, unset_substitute_path_command,
            _("\
+Delete one or all substitution rules rewriting source files names directories.\n\
 Usage: unset substitute-path [FROM]\n\
 Delete the rule for substituting FROM in source file names.  If FROM\n\
 is not specified, all substituting rules are deleted.\n\
@@ -1946,6 +1948,7 @@  If the debugger cannot find a rule for FROM, it will display a warning."),
 
   add_cmd ("substitute-path", class_files, show_substitute_path_command,
            _("\
+Show one or all substitution rules rewriting source files names directories.\n\
 Usage: show substitute-path [FROM]\n\
 Print the rule for substituting FROM in source file names. If FROM\n\
 is not specified, print all substitution rules."),
diff --git a/gdb/stack.c b/gdb/stack.c
index b3d113d3b4..eb4d5adf15 100644
--- a/gdb/stack.c
+++ b/gdb/stack.c
@@ -110,8 +110,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\
@@ -123,8 +123,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 */
   },
 
@@ -3299,7 +3299,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);
@@ -3381,7 +3381,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\
diff --git a/gdb/symfile.c b/gdb/symfile.c
index 6f9c81c8b9..29b85195e3 100644
--- a/gdb/symfile.c
+++ b/gdb/symfile.c
@@ -3944,8 +3944,8 @@  that lies within the boundaries of this symbol file in memory."),
 	       &cmdlist);
 
   c = add_cmd ("load", class_files, load_command, _("\
-Dynamically load FILE into the running program, and record its symbols\n\
-for access from GDB.\n\
+Dynamically load FILE into the running program.\n\
+FILE symbols are recorded for access from GDB.\n\
 Usage: load [FILE] [OFFSET]\n\
 An optional load OFFSET may also be given as a literal address.\n\
 When OFFSET is provided, FILE must also be provided.  FILE can be provided\n\
diff --git a/gdb/symtab.c b/gdb/symtab.c
index 4920d94a24..cc97ea1d04 100644
--- a/gdb/symtab.c
+++ b/gdb/symtab.c
@@ -6051,8 +6051,7 @@  Prints the functions.\n"),
   add_setshow_enum_cmd ("multiple-symbols", no_class,
                         multiple_symbols_modes, &multiple_symbols_mode,
                         _("\
-Set the debugger behavior when more than one symbol are possible matches\n\
-in an expression."), _("\
+Set how the debugger handles ambiguities in expressions."), _("\
 Show how the debugger handles ambiguities in expressions."), _("\
 Valid values are \"ask\", \"all\", \"cancel\", and the default is \"all\"."),
                         NULL, NULL, &setlist, &showlist);
diff --git a/gdb/target-descriptions.c b/gdb/target-descriptions.c
index bd33091ba9..6805d9e415 100644
--- a/gdb/target-descriptions.c
+++ b/gdb/target-descriptions.c
@@ -1845,8 +1845,8 @@  Unset target description specific variables."),
   add_setshow_filename_cmd ("filename", class_obscure,
 			    &tdesc_filename_cmd_string,
 			    _("\
-Set the file to read for an XML target description"), _("\
-Show the file to read for an XML target description"), _("\
+Set the file to read for an XML target description."), _("\
+Show the file to read for an XML target description."), _("\
 When set, GDB will read the target description from a local\n\
 file instead of querying the remote target."),
 			    set_tdesc_filename_cmd,
@@ -1854,8 +1854,8 @@  file instead of querying the remote target."),
 			    &tdesc_set_cmdlist, &tdesc_show_cmdlist);
 
   add_cmd ("filename", class_obscure, unset_tdesc_filename_cmd, _("\
-Unset the file to read for an XML target description.  When unset,\n\
-GDB will read the description from the target."),
+Unset the file to read for an XML target description.\n\
+When unset, GDB will read the description from the target."),
 	   &tdesc_unset_cmdlist);
 
   add_cmd ("c-tdesc", class_maintenance, maint_print_c_tdesc_cmd, _("\
@@ -1866,6 +1866,7 @@  Print the current target description as a C source file."),
 
   cmd = add_cmd ("xml-descriptions", class_maintenance,
 		 maintenance_check_xml_descriptions, _("\
+Check equality of GDB target descriptions and XML created descriptions.\n\
 Check the target descriptions created in GDB equal the descriptions\n\
 created from XML files in the directory.\n\
 The parameter is the directory name."),
diff --git a/gdb/testsuite/gdb.base/help.exp b/gdb/testsuite/gdb.base/help.exp
index e65f7c875f..921b3807f6 100644
--- a/gdb/testsuite/gdb.base/help.exp
+++ b/gdb/testsuite/gdb.base/help.exp
@@ -80,7 +80,8 @@  gdb_test "help commands" "Set commands to be executed when the given breakpoints
 # Test a prefix command.  "delete" is picked at random.
 # test help delete "d" abbreviation
 set expected_help_delete {
-    "Delete some breakpoints or auto-display expressions\.\[\r\n\]+"
+    "Delete all or some breakpoints or auto-display expressions\.\[\r\n\]+"
+    "Usage: delete \\\[BREAKPOINTNUM\\\]...\[\r\n\]+"
     "Arguments are breakpoint numbers with spaces in between\.\[\r\n\]+"
     "To delete all breakpoints, give no argument\.\[\r\n\]+"
     "Also a prefix command for deletion of other GDB objects\.\[\r\n\]+"
@@ -117,8 +118,18 @@  gdb_test "help info bogus-gdb-command" "Undefined info command: \"bogus-gdb-comm
 gdb_test "help gotcha" "Undefined command: \"gotcha\"\.  Try \"help\"\." "help gotcha"
 
 # test apropos regex
-gdb_test "apropos \\\(print\[\^\[ bsiedf\\\".-\]\\\)" "handle -- Specify how to handle signals"
+gdb_test "apropos \\\(print\[\^\[ bsiedf\\\".-\]\\\)" "handle -- Specify how to handle signals\."
 # test apropos >1 word string
-gdb_test "apropos handle signal" "handle -- Specify how to handle signals"
+gdb_test "apropos handle signal" "handle -- Specify how to handle signals\."
 # test apropos apropos
 gdb_test "apropos apropos" "apropos -- Search for commands matching a REGEXP.*"
+
+# Verify the following invariants for the doc help of all commands:
+#   First line is terminated by a '.' character.
+#   The last character of the doc is not a new line.
+# To test this last invariant, GDB apropos command outputs a line
+# that starts with END_OF_LINE@END_OF_DOC when it finds such
+# a new line at the end of a help doc.
+gdb_test_no_output \
+    "|apropos .| grep -e '\[^\.\]$' -e '^END_OF_LINE@END_OF_DOC '" \
+    "command help doc first line ends with a dot, doc does not end with eol"
diff --git a/gdb/testsuite/gdb.base/style.exp b/gdb/testsuite/gdb.base/style.exp
index a17f201486..5de1ad64c6 100644
--- a/gdb/testsuite/gdb.base/style.exp
+++ b/gdb/testsuite/gdb.base/style.exp
@@ -101,8 +101,8 @@  save_vars { env(TERM) } {
 	[multi_line \
 	     "List of classes of commands:" \
 	     "" \
-	     "${aliases_expr} -- Aliases of other commands" \
-	     "${breakpoints_expr} -- Making program stop at certain points" \
+	     "${aliases_expr} -- Aliases of other commands\." \
+	     "${breakpoints_expr} -- Making program stop at certain points\." \
 	     ".*" \
 	    ] \
 	"help classes of commands styled with title"
diff --git a/gdb/top.c b/gdb/top.c
index 857207c376..bfb4427cc8 100644
--- a/gdb/top.c
+++ b/gdb/top.c
@@ -2109,8 +2109,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);
@@ -2142,9 +2142,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."),
@@ -2168,8 +2168,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,
@@ -2224,7 +2224,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);
diff --git a/gdb/tracefile-tfile.c b/gdb/tracefile-tfile.c
index 593556a8ba..4f0c41bce5 100644
--- a/gdb/tracefile-tfile.c
+++ b/gdb/tracefile-tfile.c
@@ -43,7 +43,8 @@ 
 static const target_info tfile_target_info = {
   "tfile",
   N_("Local trace dump file"),
-  N_("Use a trace file as a target.  Specify the filename of the trace file.")
+  N_("Use a trace file as a target.\n\
+Specify the filename of the trace file.")
 };
 
 class tfile_target final : public tracefile_target
diff --git a/gdb/tracepoint.c b/gdb/tracepoint.c
index af5dcd1e33..5a499227e5 100644
--- a/gdb/tracepoint.c
+++ b/gdb/tracepoint.c
@@ -4001,7 +4001,7 @@  _initialize_tracepoint (void)
   tracepoint_number = -1;
 
   add_info ("scope", info_scope_command,
-	    _("List the variables local to a scope"));
+	    _("List the variables local to a scope."));
 
   add_cmd ("tracepoints", class_trace,
 	   _("Tracing of program execution without stopping the program."),
@@ -4031,7 +4031,7 @@  Status of trace state variables and their values."));
 List target static tracepoints markers."));
 
   add_prefix_cmd ("tfind", class_trace, tfind_command, _("\
-Select a trace frame;\n\
+Select a trace frame.\n\
 No argument means forward by one frame; '-' means backward by one frame."),
 		  &tfindlist, "tfind ", 1, &cmdlist);
 
@@ -4132,8 +4132,8 @@  depending on target's capabilities."));
   default_collect = xstrdup ("");
   add_setshow_string_cmd ("default-collect", class_trace,
 			  &default_collect, _("\
-Set the list of expressions to collect by default"), _("\
-Show the list of expressions to collect by default"), NULL,
+Set the list of expressions to collect by default."), _("\
+Show the list of expressions to collect by default."), NULL,
 			  NULL, NULL,
 			  &setlist, &showlist);
 
@@ -4173,22 +4173,22 @@  disables any attempt to set the buffer size and lets the target choose."),
 
   add_setshow_string_cmd ("trace-user", class_trace,
 			  &trace_user, _("\
-Set the user name to use for current and future trace runs"), _("\
-Show the user name to use for current and future trace runs"), NULL,
+Set the user name to use for current and future trace runs."), _("\
+Show the user name to use for current and future trace runs."), NULL,
 			  set_trace_user, NULL,
 			  &setlist, &showlist);
 
   add_setshow_string_cmd ("trace-notes", class_trace,
 			  &trace_notes, _("\
-Set notes string to use for current and future trace runs"), _("\
-Show the notes string to use for current and future trace runs"), NULL,
+Set notes string to use for current and future trace runs."), _("\
+Show the notes string to use for current and future trace runs."), NULL,
 			  set_trace_notes, NULL,
 			  &setlist, &showlist);
 
   add_setshow_string_cmd ("trace-stop-notes", class_trace,
 			  &trace_stop_notes, _("\
-Set notes string to use for future tstop commands"), _("\
-Show the notes string to use for future tstop commands"), NULL,
+Set notes string to use for future tstop commands."), _("\
+Show the notes string to use for future tstop commands."), NULL,
 			  set_trace_stop_notes, NULL,
 			  &setlist, &showlist);
 }
diff --git a/gdb/tui/tui-win.c b/gdb/tui/tui-win.c
index 575620f4c8..b1f6fcb8fd 100644
--- a/gdb/tui/tui-win.c
+++ b/gdb/tui/tui-win.c
@@ -1657,11 +1657,11 @@  _initialize_tui_win (void)
   /* Define the classes of commands.
      They will appear in the help list in the reverse of this order.  */
   add_prefix_cmd ("tui", class_tui, set_tui_cmd,
-                  _("TUI configuration variables"),
+                  _("TUI configuration variables."),
 		  &tui_setlist, "set tui ",
 		  0 /* allow-unknown */, &setlist);
   add_prefix_cmd ("tui", class_tui, show_tui_cmd,
-                  _("TUI configuration variables"),
+                  _("TUI configuration variables."),
 		  &tui_showlist, "show tui ",
 		  0 /* allow-unknown */, &showlist);
 
@@ -1756,7 +1756,7 @@  This variable controls the attributes to use for the active window border:\n\
   add_setshow_zuinteger_cmd ("tab-width", no_class,
 			     &internal_tab_width, _("\
 Set the tab width, in characters, for the TUI."), _("\
-Show the tab witdh, in characters, for the TUI"), _("\
+Show the tab witdh, in characters, for the TUI."), _("\
 This variable controls how many spaces are used to display a tab character."),
 			     tui_set_tab_width, tui_show_tab_width,
 			     &tui_setlist, &tui_showlist);
diff --git a/gdb/utils.c b/gdb/utils.c
index f55661287e..88450cccba 100644
--- a/gdb/utils.c
+++ b/gdb/utils.c
@@ -530,10 +530,10 @@  add_internal_problem_command (struct internal_problem *problem)
   if (problem->user_settable_should_quit)
     {
       set_doc = xstrprintf (_("Set whether GDB should quit "
-			      "when an %s is detected"),
+			      "when an %s is detected."),
 			    problem->name);
       show_doc = xstrprintf (_("Show whether GDB will quit "
-			       "when an %s is detected"),
+			       "when an %s is detected."),
 			     problem->name);
       add_setshow_enum_cmd ("quit", class_maintenance,
 			    internal_problem_modes,
@@ -553,10 +553,10 @@  add_internal_problem_command (struct internal_problem *problem)
   if (problem->user_settable_should_dump_core)
     {
       set_doc = xstrprintf (_("Set whether GDB should create a core "
-			      "file of GDB when %s is detected"),
+			      "file of GDB when %s is detected."),
 			    problem->name);
       show_doc = xstrprintf (_("Show whether GDB will create a core "
-			       "file of GDB when %s is detected"),
+			       "file of GDB when %s is detected."),
 			     problem->name);
       add_setshow_enum_cmd ("corefile", class_maintenance,
 			    internal_problem_modes,
diff --git a/gdb/valprint.c b/gdb/valprint.c
index 6f9b47da80..0a4cc8e971 100644
--- a/gdb/valprint.c
+++ b/gdb/valprint.c
@@ -3140,7 +3140,7 @@  static const gdb::option::option_def value_print_option_defs[] = {
     [] (value_print_options *opt) { return &opt->print_array_indexes; },
     show_print_array_indexes, /* show_cmd_cb */
     N_("Set printing of array indexes."),
-    N_("Show printing of array indexes"),
+    N_("Show printing of array indexes."),
     NULL, /* help_doc */
   },