[2/3] deprecate "skip enable/etc.", doc string cleanup

  This patch deprecates "skip enable", "skip disable", "skip delete"
in favor of "enable skip", "disable skip", "delete skip".
And it uses the doc string macros of 1/3.

2016-04-17  Doug Evans  <dje@google.com>

	* NEWS: Announce new skip commands, and deprecated ones.
	* skip.c (_initialize_step_skip): Deprecate "skip enable",
	"skip disable", "skip delete" in favor of "enable skip",
	"disable skip", "delete skip". Simplify doc strings.

	doc/
	* gdb.texinfo (Skipping Over Functions and Files): Add docs for
	"enable skip", "disable skip", "delete skip". Mark "skip enable",
	"skip disable", "skip delete" as deprecated.

  @item skip delete @r{[}@var{range}@r{]}
  Delete the specified skip(s).  If @var{range} is not specified, delete all
  

> Date: Mon, 18 Apr 2016 15:47:21 +0000
> From: Doug Evans <dje@google.com>
> 
> This patch deprecates "skip enable", "skip disable", "skip delete"
> in favor of "enable skip", "disable skip", "delete skip".
> And it uses the doc string macros of 1/3.

OK, but I still don't like those macros.  They make it harder to
understand how the doc string will read.
  

On Mon, Apr 18, 2016 at 11:57 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Mon, 18 Apr 2016 15:47:21 +0000
>> From: Doug Evans <dje@google.com>
>>
>> This patch deprecates "skip enable", "skip disable", "skip delete"
>> in favor of "enable skip", "disable skip", "delete skip".
>> And it uses the doc string macros of 1/3.
>
> OK, but I still don't like those macros.  They make it harder to
> understand how the doc string will read.

I'm just going with the flow here.
The explicit locations patch did this (perhaps not
as parameterized as I've done here, but I am
improving the docs here - before it was just
"Give breakpoint numbers." and now it's
something vastly more useful).

The alternative is to describe such things (in this case
how to specify breakpoint/etc. numbers) in one place
and then add a "See mumble." to all the other places.
I actually did that, and then remembered the explicit
locations discussion. And then spent a lot of time
waffling "Crap, what will upstream accept?"
and in the decided to stick with existing practice.

I certainly don't want to replicate all that text again
and again (hence the macros).
  

> From: Doug Evans <dje@google.com>
> Date: Mon, 18 Apr 2016 12:42:04 -0700
> Cc: gdb-patches <gdb-patches@sourceware.org>
> 
> I certainly don't want to replicate all that text again
> and again (hence the macros).

I understand, but put yourself in the position of someone who needs to
review a patch, and sees something like this:

  +Display the status of skips.\n"
  +EDDI_USAGE_DOC_STRING_WITH_ALL ("skip", "info skip", "displayed")));

How does that someone know if the resulting text is good English and
will produce a clear help text, or needs to be fixed in some way?
  

On Mon, Apr 18, 2016 at 12:53 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Doug Evans <dje@google.com>
>> Date: Mon, 18 Apr 2016 12:42:04 -0700
>> Cc: gdb-patches <gdb-patches@sourceware.org>
>>
>> I certainly don't want to replicate all that text again
>> and again (hence the macros).
>
> I understand, but put yourself in the position of someone who needs to
> review a patch, and sees something like this:
>
>   +Display the status of skips.\n"
>   +EDDI_USAGE_DOC_STRING_WITH_ALL ("skip", "info skip", "displayed")));
>
> How does that someone know if the resulting text is good English and
> will produce a clear help text, or needs to be fixed in some way?

I'm open to suggestions.

I really hope the solution is to not expand all those macro
invocations in place.
  

On 04/18/2016 09:01 PM, Doug Evans wrote:
> On Mon, Apr 18, 2016 at 12:53 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>>> From: Doug Evans <dje@google.com>
>>> Date: Mon, 18 Apr 2016 12:42:04 -0700
>>> Cc: gdb-patches <gdb-patches@sourceware.org>
>>>
>>> I certainly don't want to replicate all that text again
>>> and again (hence the macros).
>>
>> I understand, but put yourself in the position of someone who needs to
>> review a patch, and sees something like this:
>>
>>   +Display the status of skips.\n"
>>   +EDDI_USAGE_DOC_STRING_WITH_ALL ("skip", "info skip", "displayed")));
>>
>> How does that someone know if the resulting text is good English and
>> will produce a clear help text, or needs to be fixed in some way?
> 
> I'm open to suggestions.
> 
> I really hope the solution is to not expand all those macro
> invocations in place.
> 

I think the answer is to include the before/after GDB output in
the mail submission / git log.

We actually already ask for that in the contribution checklist [1]:

 "If you're changing the output of some command, include a paste of the
 relevant parts of gdb session, before and after the change."

[1] - https://sourceware.org/gdb/wiki/ContributionChecklist#General_requirements

Thanks,
Pedro Alves
  

> From: Doug Evans <dje@google.com>
> Date: Mon, 18 Apr 2016 13:01:37 -0700
> Cc: gdb-patches <gdb-patches@sourceware.org>
> 
> On Mon, Apr 18, 2016 at 12:53 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> >> From: Doug Evans <dje@google.com>
> >> Date: Mon, 18 Apr 2016 12:42:04 -0700
> >> Cc: gdb-patches <gdb-patches@sourceware.org>
> >>
> >> I certainly don't want to replicate all that text again
> >> and again (hence the macros).
> >
> > I understand, but put yourself in the position of someone who needs to
> > review a patch, and sees something like this:
> >
> >   +Display the status of skips.\n"
> >   +EDDI_USAGE_DOC_STRING_WITH_ALL ("skip", "info skip", "displayed")));
> >
> > How does that someone know if the resulting text is good English and
> > will produce a clear help text, or needs to be fixed in some way?
> 
> I'm open to suggestions.
> 
> I really hope the solution is to not expand all those macro
> invocations in place.

If I'm the only one who is bothered by such macro-izing of doc
strings, then just ignore me.