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

[Pedro Alves <palves at redhat dot com>]

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