[PATCH 00/24] Remove TRAD_SYNOPSIS

[Jon Turney]

On 01/12/2017 09:38, Corinna Vinschen wrote:
> On Nov 30 18:08, Yaakov Selkowitz wrote:
>> On 2017-11-30 12:05, Corinna Vinschen wrote:
>>> On Nov 30 12:40, Craig Howland wrote:
>>>> 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,
>>>>>
>>>> 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.
>>>
>>> That was the idea: The doc building process should not simply fail but
>>> explain what's wrong and just print a matching message during build:
>>>
>>>    "bla bla, outdated, remove TRAD_SYNOPSIS and rename ANSI_SYNOPSIS
>>>     to SYNOPSIS, bla, bla"
>>
>> Apparently error messages during doc building are printed to a
>> non-obvious location, meaning these probably wouldn't be seen.  Simply
>> removing any mention of these tags apparently causes them to be ignored.

To amplify on this, in Makefile.shared we currently have:

> CHEW = ${top_builddir}/../doc/makedoc -f $(top_srcdir)/../doc/doc.str
> 
> .c.def:
>         $(CHEW) < $< > $*.def 2> $*.ref

makedoc outputs something related to QUICKREF to stderr, along with any 
errors or warnings it produces.

Presumably the .ref file was at some stage intended to be used to 
produce some sort of 'quick reference', but the details are lost in time...

I'd suggest that QUICKREF is turned into a no-op, and then we can stop 
redirecting the output of makedoc.

>>   Is there a way to raise an error when these tags are found?
>>
>> If there is no simple solution to this, perhaps we should consider this
>> separately from the existing patchset.
> 
> Makes sense.  ACK to the series.