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

[Joel Brobecker <brobecker@adacore.com>]

Hi Eli,

Since you are the official Maintainer of the GDB documentation,
would you mind telling us what you think? I'd like us to make
a decision, so that I can redo the documentation that goes
with the patch.

Thank you!

> > 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.
> 
> I understand your reasoning, and can agree with you in the sense
> that someone already using the deprecated command might want to
> look some detail up in the GDB manual and not find it.
> 
> But I do not have a strong opininon on this, and whatever we end up
> deciding is fine by me. Let's just decide now :). I will go with #3,
> or else #2.
> 
> -- 
> Joel

-- 
Joel