The concept of 'one single line' help gives strange effects ...

[Philippe Waroquiers]

In a recent HEAD gdb, do the following:
(gdb) |apropos .|cat > apropos1.out
(gdb) |apropos -v .|grep -e ' -- ' | sed -e 's/\.$//' > apropos1bis.out
(gdb) !diff apropos1.out apropos1bis.out|more

This will (mostly) show the difference between the 'truncated' first line
of help, as produced by 'help <some class>' or 'apropos REGEXP'
and the first 'full line' of the help, as output by
  'apropos -v REGEXP' or by 'help command'.

The 'truncated' first line is produced by cli-decode.c:print_doc_line.
This stops printing characters of the first line when encountering a .
or a , character.

This has not been taken into account in all help strings, giving
sometimes cumbersome one line help.

E.g., the full first line help for 'catch exception'
and 'catch handlers' are:
> catch exception -- Catch Ada exceptions, when raised
> catch handlers -- Catch Ada exceptions, when handled

while the truncated one line help is:
< catch exception -- Catch Ada exceptions
< catch handlers -- Catch Ada exceptions

Probably the intent was not to have the second part of the line
removed, as otherwise the 2 commands looks like alias, while
they are really different commands.

There are other strange cases like that, e.g.
< catch syscall -- Catch system calls by their names
> catch syscall -- Catch system calls by their names, groups and/or numbers

< down-silently -- Same as the `down' command
> down-silently -- Same as the `down' command, but does not print anything

....

On the other hand, some first line help have been done
based on the assumption that what follows a . or a , are details
not to be shown in a one line help.
e.g.
< enable once -- Enable breakpoints for one hit
---
> enable once -- Enable breakpoints for one hit.  Give breakpoint numbers


Wondering if/how to make all this more consistent.

Maybe print_doc_line should continue till a . character ?
  (i.e. not stop anymore at a ,) ?

(that will imply to change the help of a few commands that were
counting on the single line help to be truncated at ,.

Philippe