This is the mail archive of the
mailing list for the GDB project.
Re: [RFA] Make first and last lines of 'command help documentation' consistent.
- From: Tom Tromey <tom at tromey dot com>
- To: Philippe Waroquiers <philippe dot waroquiers at skynet dot be>
- Cc: gdb-patches at sourceware dot org
- Date: Wed, 10 Jul 2019 11:02:42 -0600
- Subject: Re: [RFA] Make first and last lines of 'command help documentation' consistent.
- References: <firstname.lastname@example.org>
>>>>> "Philippe" == Philippe Waroquiers <email@example.com> 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> 2019-06-16 Philippe Waroquiers <firstname.lastname@example.org>
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> * 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\
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.