On Thu, Jun 22, 2017 at 01:40:10PM +0200, Ingo Schwarze wrote:
> Hi Anthony,
>
> Anthony J. Bentley wrote on Thu, Jun 22, 2017 at 12:21:55AM -0600:
>
> > ok?
>
> NO, definitely NOT OK without a thorough rationale.
>
i imagine the rationale is the existence of -p1003.1-2013 ;)
> We do not add definitions just like that. The file st.in
> has lots of irrelevant definitions already, and i won't let
> that trend continue.
>
> If i remember correctly, jmc@ has laboriously ploughed though the
> whole of Cor 2-2016, updated all section 1 manuals to refer to
> 1003.1-2008, and did not find a single manual page where it is of
> interest to talk about the corrigendum. It seems to me that the
> corrigendum corrects editorial errors and edge cases that are not
> mentioned in our manual page in the first place rather than changing
> requirements for user-visible functionality, and it is not to be
> wondered at because that's indeed the point of a technical corrigendum.
>
well in the case of 2016 i skimmed through the changes since the last
revision. i certainly didn;t find any changes that required documenting.
so do you want to remove the entry for 1003.1-2013 as well? none of our
man pages use it.
jmc
> Even if you find a handful of cases where mentioning the corrigendum
> in the manual page seems beneficial, i deem it likely that saying
> just "1003.1-2008/Cor 2-2016" there is unclear and confusing, failing
> to make it clear that this is a very unusual case where the corrigendum
> substantially changed requirements such that the utility now confors
> to 1003.1-2008/Cor 2-2016, but NOT to 1003.1-2008.
>
> In such an unusual a case, i'd prefer writing a conspicious sentence
> like
>
> The
> .Nm formerly_broken
> utility is compliant with the
> .St -p1003.1-2008
> specification.
> .Pp
> Note that the second technical corrigendum of that specification,
> published in 2016, substantially changed the requirements for
> the
> .Fl x
> option, and this implementations conforms to what that corrigendum
> requires.
>
> rather than a mere
>
> The
> .Nm formerly_broken
> utility is compliant with the
> .St -p1003.1-2016
> specification.
>
> trying to say the same, which will almost certainly be overlooked
> in practice, or even if somebody notices the unusual "Cor 2" in the
> output, it is still likely that they fail to understand that this
> implies that the specification changed substantially in 2016 with
> respect to the utility - thus setting a trap for users.
>
> Yours,
> Ingo
>
>
> > Index: share/man/man7/mdoc.7
> > ===================================================================
> > RCS file: /cvs/src/share/man/man7/mdoc.7,v
> > retrieving revision 1.153
> > diff -u -p -r1.153 mdoc.7
> > --- share/man/man7/mdoc.7 10 Jun 2017 16:32:08 -0000 1.153
> > +++ share/man/man7/mdoc.7 22 Jun 2017 06:20:33 -0000
> > @@ -2593,6 +2593,11 @@ X/Open Portability Guide version 7.
> > .St -p1003.1-2013
> > .br
> > This is the first Technical Corrigendum.
> > +.Pp
> > +.It \-p1003.1-2016
> > +.St -p1003.1-2016
> > +.br
> > +This is the second Technical Corrigendum.
> > .El
> > .It Other standards
> > .Pp
> > Index: usr.bin/mandoc/st.in
> > ===================================================================
> > RCS file: /cvs/src/usr.bin/mandoc/st.in,v
> > retrieving revision 1.22
> > diff -u -p -r1.22 st.in
> > --- usr.bin/mandoc/st.in 17 Feb 2015 20:33:44 -0000 1.22
> > +++ usr.bin/mandoc/st.in 22 Jun 2017 06:20:33 -0000
> > @@ -35,6 +35,7 @@ LINE("-p1003.1-2001", "IEEE Std 1003.1-2
> > LINE("-p1003.1-2004", "IEEE Std 1003.1-2004 (\\(LqPOSIX.1\\(Rq)")
> > LINE("-p1003.1-2008", "IEEE Std 1003.1-2008 (\\(LqPOSIX.1\\(Rq)")
> > LINE("-p1003.1-2013", "IEEE Std 1003.1-2008/Cor 1-2013
> > (\\(LqPOSIX.1\\(Rq)")
> > +LINE("-p1003.1-2016", "IEEE Std 1003.1-2008/Cor 2-2016
> > (\\(LqPOSIX.1\\(Rq)")
> > LINE("-p1003.1", "IEEE Std 1003.1 (\\(LqPOSIX.1\\(Rq)")
> > LINE("-p1003.1b", "IEEE Std 1003.1b (\\(LqPOSIX.1b\\(Rq)")
> > LINE("-p1003.1b-93", "IEEE Std 1003.1b-1993 (\\(LqPOSIX.1b\\(Rq)")
>
