Re: [PATCH 00/24] Remove TRAD_SYNOPSIS

[Craig Howland <howland at LGSInnovations dot com>]

On 11/30/2017 11:11 AM, Corinna Vinschen wrote:
> On Nov 30 10:53, Craig Howland wrote:
> > On 11/30/2017 05:28 AM, Yaakov Selkowitz wrote:
> > > This completely removes TRAD_SYNOPSIS and renames ANSI_SYNOPSIS to
> > > SYNOPSIS throughout Newlib's docuemntation.  I'm just not sure about
> > > the doc tools themselves; should support for both of those names also
> > > be removed?
> > A thought is to leave them in the doc tools.  Since the tools treat SYNOPSIS
> > and ANSI_SYNOPSIS the same, they'll work the same with or without the
> > present change.  Leaving in TRAD_SYNOPSIS as something to be ignored plus
> > keeping ANSI_SYNOPSIS as working could possibly help out people that have
> > added their own stuff, not forcing them to make these same changes.
> > (Probably a very small to non-existent set of people, but it is difficult to
> > know if there are any or not.)  It doesn't seem to hurt anything to leave
> > them, although adding a note that they have been retained for legacy
> > purposes might be a good idea.
> Wouldn't it be better in the long run to fail on seeing a TRAD_SYNOPSIS
> or ANSI_SYNOPSIS and tell the dev to remove the first and to rename the
> latter?  It's not very hard to fix,
>
> Corinna
It depends on your point of view.  I agree that it is easy to fix, but the idea 
of keeping it was thinking that if I happened to have files that suddenly became 
obsolete and I had to spend to to alter the word I would be annoyed at the waste 
of time:  discover the problem, track down how to fix it, then do it.  Figuring 
it out would likely be the longest.  So either way works, but I gave it as an 
idea as perhaps avoiding some frustration that could be avoided. Your idea for a 
direct message that those two names are now no good it would eliminate the 
track-down step I had thought of, and would make it quite a bit better.
Craig