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"