[PATCH 00/24] Remove TRAD_SYNOPSIS

[Yaakov Selkowitz]

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.
 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.

-- 
Yaakov

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: OpenPGP digital signature
URL: <http://sourceware.org/pipermail/newlib/attachments/20171201/5106e8af/attachment.sig>