Re: [Windows/RFA/commit] Deprecate windows-specific dll-symbols command and aliases

[Pedro Alves <palves at redhat dot com>]

On 02/10/2014 02:34 PM, Joel Brobecker wrote:

> My 2 cents: I think it's fine to either remove the documentation, or
> else leave it as is. Adding more info as you suggest is indeed making
> the documentation better, but only for a short period of time. 

"short period of time" here doesn't seem all that correct to me.
Sure, it's short if you track mainline.  But a user using a
release will be looking at the documentation of the gdb version
she is using.  In that perspective, the fact that mainline has
already changed is not what dictates how long the user sees
the documentation.  The next upgrade cycle does.

> During
> that period of time, if people happen to read about the deprecated
> command in the manual, and then actually use that function, they'll
> immediately get a warning, the warning will tell them which command to
> use in its place. On the other hand, if we excise the commands'
> documentation and they are searching the users manual, the only
> command they can find are the non-deprecated ones.
> 
> In that respect, I now tend to agree with Eli. But it's not a strong
> opinion.

Alright, so AIUI, the argument for deleting seems to be that we
should not advertise deprecated commands.

IOW, we should avoid that people reading the manual end up using
deprecated commands when a better alternative exists, and the
deprecated command might well be removed soon.

I completely agree that we should avoid that.  What I don't agree
is that deleting the documentation is the only way to do that.
I believe that adding a note to the command's documentation in
the manual saying the command is deprecated and pointing at the
better alternative would do just as well.

I'm of the opinion that as long as the command exists, it
should be documented.  Sure, by being deprecated, the user
should no longer rely on its existence, but it might take
a while for said user to actually upgrade to a gdb that
actually removes the command (if we ever do), and there's
no need IMO to make it more painful for the user to
look up documentation for the command she is actually
currently using right now to solve some hard to catch
bug in her application.  If we remove the documentation,
then she has to do look for a manual of an older gdb.

Note that old -> new command mapping might not be
trivial, it might need adjustment of command parameters,
and might well be that the new form is actually a sequence
of commands, not a single command.

(Note that I'm talking about policy here, not about
any specific command.)

So it seems like we have 3 possible policies:

 #1 - Leave the manual unchanged when we deprecate commands.  Delete
      the documentation at the same time the command is actually
      deleted.

 #2 - Always excise documentation for deprecated commands at the same
     time we do the deprecation.

 #3 - Mark the commands deprecated in the manual at the same time
      we mark them deprecated in the code.  Delete the documentation
      at the same time the command is actually deleted.

In my view, #1 is just a bad policy.  Having documentation
for deprecated commands behind _without_ a "deprecated,
use foo instead" note in them might lead users to find
the old command and start using them while newer better
alternatives exist.  I think everyone will agree to that.

And in my view, #3 is a superior policy than #2.  But
I'll accept #2, if that's what the group ends up preferring.

Whatever we end up deciding, I think we should document
the outcome as guideline somewhere in the internals
manual, and if we go with #2, then we it'd be good
to make a pass over the manual and remove all the
existing documentation for currently deprecated
commands.

Thanks,
-- 
Pedro Alves