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