Make first and last lines of 'command help documentation' consistent.
authorPhilippe Waroquiers <philippe.waroquiers@skynet.be>
Sun, 9 Jun 2019 09:16:20 +0000 (11:16 +0200)
committerPhilippe Waroquiers <philippe.waroquiers@skynet.be>
Tue, 6 Aug 2019 22:04:33 +0000 (00:04 +0200)
commit590042fc45f857c981bee4e0c76f6b3b528a224e
treebcf2a412f5fecb0114a41ea0d837d6ff477ed2d6
parent404f29021abaef86a341663444fb069eb1f0282a
Make first and last lines of 'command help documentation' consistent.

With this patch, the help docs now respect 2 invariants:
  * The first line of a command help is terminated by a '.' character.
  * The last character of a command help is not a newline character.

Note that the changes for the last invariant were done by Tom, as part of :
 [PATCH] Remove trailing newlines from help text
 https://sourceware.org/ml/gdb-patches/2019-06/msg00050.html
but some occurrences have been re-introduced since then.

Some help docs had to be rephrased/restructured to respect the above
invariants.

Before this patch, print_doc_line was printing the first line
of a command help documentation, but stopping at the first '.'
or ',' character.

This was giving inconsistent results :
  * The first line of command helps was sometimes '.' terminated,
    sometimes not.
  * The first line of command helps was not always designed to be
    readable/understandable/unambiguous when stopping at the first
    '.' or ',' character.

This e.g. created the following inconsistencies/problems:
< catch exception -- Catch Ada exceptions
< catch handlers -- Catch Ada exceptions
< catch syscall -- Catch system calls by their names
< down-silently -- Same as the `down' command
while the new help is:
> catch exception -- Catch Ada exceptions, when raised.
> catch handlers -- Catch Ada exceptions, when handled.
> catch syscall -- Catch system calls by their names, groups and/or numbers.
> down-silently -- Same as the `down' command, but does not print anything.

Also, the command help doc should not be terminated by a newline
character, but this was not respected by all commands.
The cli-option -OPT framework re-introduced some occurences.
So, the -OPT build help framework was changed to not output newlines at the
end of %OPTIONS% replacement.

This patch changes the help documentations to ensure the 2 invariants
given above.

It implied to slightly rephrase or restructure some help docs.

Based on the above invariants, print_doc_line (called by
'apropos' and 'help' commands to print the first line of a command
help) now outputs the full first line of a command help.

This all results in a lot of small changes in the produced help docs.
There are less code changes than changes in the help docs, as a lot
of docs are produced by some code (e.g. the remote packet usage settings).

gdb/ChangeLog
2019-08-07  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

* cli/cli-decode.h (print_doc_line): Add for_value_prefix argument.
* cli/cli-decode.c (print_doc_line): Likewise.  It now prints
the full first line, except when FOR_VALUE_PREFIX.  In this case,
the trailing '.' is not output, and the first character is uppercased.
(print_help_for_command): Update call to print_doc_line.
(print_doc_of_command): Likewise.
* cli/cli-setshow.c (deprecated_show_value_hack): Likewise.
* cli/cli-option.c (append_indented_doc): Do not append newline.
(build_help_option): Append newline after first appended_indented_doc
only if a second call is done.
(build_help): Append 2 new lines before each option, except the first
one.
* compile/compile.c (_initialize_compile): Add new lines after
%OPTIONS%, when not at the end of the help.
Change help doc or code
producing the help doc to respect the invariants.
* maint-test-options.c (_initialize_maint_test_options): Likewise.
Also removed the new line after 'Options:', as all other commands
do not put an empty line between 'Options:' and the first option.
* printcmd.c (_initialize_printcmd): Likewise.
* stack.c (_initialize_stack): Likewise.
* interps.c (interpreter_exec_cmd): Fix "Usage:" line that was
incorrectly telling COMMAND is optional.
* ada-lang.c (_initialize_ada_language): Change help doc or code
producing the help doc to respect the invariants.
* ada-tasks.c (_initialize_ada_tasks): Likewise.
* breakpoint.c (_initialize_breakpoint): Likewise.
* cli/cli-cmds.c (_initialize_cli_cmds): Likewise.
* cli/cli-logging.c (_initialize_cli_logging): Likewise.
* cli/cli-setshow.c (_initialize_cli_setshow): Likewise.
* cli/cli-style.c (cli_style_option::add_setshow_commands,
_initialize_cli_style): Likewise.
* corelow.c (core_target_info): Likewise.
* dwarf-index-cache.c (_initialize_index_cache): Likewise.
* dwarf2read.c (_initialize_dwarf2_read): Likewise.
* filesystem.c (_initialize_filesystem): Likewise.
* frame.c (_initialize_frame): Likewise.
* gnu-nat.c (add_task_commands): Likewise.
* infcall.c (_initialize_infcall): Likewise.
* infcmd.c (_initialize_infcmd): Likewise.
* interps.c (_initialize_interpreter): Likewise.
* language.c (_initialize_language): Likewise.
* linux-fork.c (_initialize_linux_fork): Likewise.
* maint-test-settings.c (_initialize_maint_test_settings): Likewise.
* maint.c (_initialize_maint_cmds): Likewise.
* memattr.c (_initialize_mem): Likewise.
* printcmd.c (_initialize_printcmd): Likewise.
* python/lib/gdb/function/strfns.py (_MemEq, _StrLen, _StrEq,
_RegEx): Likewise.
* ravenscar-thread.c (_initialize_ravenscar): Likewise.
* record-btrace.c (_initialize_record_btrace): Likewise.
* record-full.c (_initialize_record_full): Likewise.
* record.c (_initialize_record): Likewise.
* regcache-dump.c (_initialize_regcache_dump): Likewise.
* regcache.c (_initialize_regcache): Likewise.
* remote.c (add_packet_config_cmd, init_remote_threadtests,
_initialize_remote): Likewise.
* ser-tcp.c (_initialize_ser_tcp): Likewise.
* serial.c (_initialize_serial): Likewise.
* skip.c (_initialize_step_skip): Likewise.
* source.c (_initialize_source): Likewise.
* stack.c (_initialize_stack): Likewise.
* symfile.c (_initialize_symfile): Likewise.
* symtab.c (_initialize_symtab): Likewise.
* target-descriptions.c (_initialize_target_descriptions): Likewise.
* top.c (init_main): Likewise.
* tracefile-tfile.c (tfile_target_info): Likewise.
* tracepoint.c (_initialize_tracepoint): Likewise.
* tui/tui-win.c (_initialize_tui_win): Likewise.
* utils.c (add_internal_problem_command): Likewise.
* valprint.c (value_print_option_defs): Likewise.

gdb/testsuite/ChangeLog
2019-08-07  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

* gdb.base/style.exp: Update tests for help doc new invariants.
* gdb.base/help.exp: Likewise.
53 files changed:
gdb/ChangeLog
gdb/ada-lang.c
gdb/ada-tasks.c
gdb/breakpoint.c
gdb/cli/cli-cmds.c
gdb/cli/cli-decode.c
gdb/cli/cli-decode.h
gdb/cli/cli-logging.c
gdb/cli/cli-option.c
gdb/cli/cli-setshow.c
gdb/cli/cli-style.c
gdb/compile/compile.c
gdb/corelow.c
gdb/dwarf-index-cache.c
gdb/dwarf2read.c
gdb/filesystem.c
gdb/frame.c
gdb/gnu-nat.c
gdb/infcall.c
gdb/infcmd.c
gdb/interps.c
gdb/language.c
gdb/linux-fork.c
gdb/maint-test-options.c
gdb/maint-test-settings.c
gdb/maint.c
gdb/memattr.c
gdb/printcmd.c
gdb/python/lib/gdb/function/strfns.py
gdb/ravenscar-thread.c
gdb/record-btrace.c
gdb/record-full.c
gdb/record.c
gdb/regcache-dump.c
gdb/regcache.c
gdb/remote.c
gdb/ser-tcp.c
gdb/serial.c
gdb/skip.c
gdb/source.c
gdb/stack.c
gdb/symfile.c
gdb/symtab.c
gdb/target-descriptions.c
gdb/testsuite/ChangeLog
gdb/testsuite/gdb.base/help.exp
gdb/testsuite/gdb.base/style.exp
gdb/top.c
gdb/tracefile-tfile.c
gdb/tracepoint.c
gdb/tui/tui-win.c
gdb/utils.c
gdb/valprint.c