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

[Tom Tromey <tom@tromey.com>]

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