| Message ID | 20171130102858.16160-1-yselkowi@redhat.com |
|---|---|
| Headers | show |
| Series | Remove TRAD_SYNOPSIS | expand |
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. Thank you for doing this. I've thought of doing this for a long while, but have never had the time to actually go ahead and do it. Craig
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 -- Corinna Vinschen Cygwin Maintainer Red Hat
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
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, > > > > 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. 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" Corinna -- Corinna Vinschen Cygwin Maintainer Red Hat
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
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. > 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. Thanks, Corinna -- Corinna Vinschen Cygwin Maintainer Red Hat
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.