Re: mdoc(7): .St for latest POSIX
Ingo Schwarze writes: > Hi Jason, > > Jason McIntyre wrote on Thu, Jun 22, 2017 at 02:07:51PM +0100: > > > so do you want to remove the entry for 1003.1-2013 as well? > > none of our man pages use it. > > The decisive point is that even current groff does not support it, > so deleting it is unlikely to break other's pages. > > OK? ok bentley@
Re: mdoc(7): .St for latest POSIX
On Fri, Jun 23, 2017 at 07:33:40PM +0200, Ingo Schwarze wrote: > Hi Jason, > > Jason McIntyre wrote on Fri, Jun 23, 2017 at 06:24:17PM +0100: > > > yes, i'm fine with removing it. > > Good, i'll commit it unless i hear objections. > > > i hate to say it, but i think it was you who added it! > > RCS file: /cvs/src/usr.bin/mandoc/st.in,v > revision 1.17 > date: 2013/12/30 09:47:43; author: schwarze; state: Exp; lines: +2 -1; > Support .St -p1003.1-2013, "IEEE Std 1003.1-2008/Cor 1-2013". > > Note that the POSIX-2008 standard remains in force, so please refrain > from wholesale 2008 -> 2013 replacements. Make sure to only use the > new -p1003.1-2013 argument for cases where "IEEE Std 1003.1(TM)-2008/ > Cor 1-2013, IEEE Standard for Information Technology--Portable > Operating System Interface (POSIX(R)), Technical Corrigendum 1" > actually changes something in the standard with respect to the > specific function documented in the manual you touch. Otherwise, > please continue using .St -p1003.1-2008. > > Triggered by a similar, but slightly incorrect patch from jmc@; > ok guenther@. > > > So, we kind of teamed up for that one, but it turns out > we didn't accomplish anything useful in this particular case. > > Yours, > Ingo > we should amend cvs blame ;) jmc
Re: mdoc(7): .St for latest POSIX
Hi Jason,
Jason McIntyre wrote on Fri, Jun 23, 2017 at 06:24:17PM +0100:
> yes, i'm fine with removing it.
Good, i'll commit it unless i hear objections.
> i hate to say it, but i think it was you who added it!
RCS file: /cvs/src/usr.bin/mandoc/st.in,v
revision 1.17
date: 2013/12/30 09:47:43; author: schwarze; state: Exp; lines: +2 -1;
Support .St -p1003.1-2013, "IEEE Std 1003.1-2008/Cor 1-2013".
Note that the POSIX-2008 standard remains in force, so please refrain
from wholesale 2008 -> 2013 replacements. Make sure to only use the
new -p1003.1-2013 argument for cases where "IEEE Std 1003.1(TM)-2008/
Cor 1-2013, IEEE Standard for Information Technology--Portable
Operating System Interface (POSIX(R)), Technical Corrigendum 1"
actually changes something in the standard with respect to the
specific function documented in the manual you touch. Otherwise,
please continue using .St -p1003.1-2008.
Triggered by a similar, but slightly incorrect patch from jmc@;
ok guenther@.
So, we kind of teamed up for that one, but it turns out
we didn't accomplish anything useful in this particular case.
Yours,
Ingo
>> 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 - 1.22
>> +++ usr.bin/mandoc/st.in 23 Jun 2017 17:04:35 -
>> @@ -34,7 +34,6 @@ LINE("-p1003.1-96","ISO/IEC 9945-1:1996
>> LINE("-p1003.1-2001", "IEEE Std 1003.1-2001 (\\(LqPOSIX.1\\(Rq)")
>> 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","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)")
>> 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.710 Jun 2017 16:32:08 - 1.153
>> +++ share/man/man7/mdoc.723 Jun 2017 17:04:35 -
>> @@ -2588,11 +2588,6 @@ The second and last Technical Corrigendu
>> .br
>> This standard is also called
>> X/Open Portability Guide version 7.
>> -.Pp
>> -.It \-p1003.1-2013
>> -.St -p1003.1-2013
>> -.br
>> -This is the first Technical Corrigendum.
>> .El
>> .It Other standards
>> .Pp
Re: mdoc(7): .St for latest POSIX
On Fri, Jun 23, 2017 at 07:05:34PM +0200, Ingo Schwarze wrote:
> Hi Jason,
>
> Jason McIntyre wrote on Thu, Jun 22, 2017 at 02:07:51PM +0100:
>
> > so do you want to remove the entry for 1003.1-2013 as well?
> > none of our man pages use it.
>
> The decisive point is that even current groff does not support it,
> so deleting it is unlikely to break other's pages.
>
> OK?
> Ingo
>
yes, i'm fine with removing it. i hate to say it, but i think it was you
who added it!
jmc
>
> 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 - 1.22
> +++ usr.bin/mandoc/st.in 23 Jun 2017 17:04:35 -
> @@ -34,7 +34,6 @@ LINE("-p1003.1-96", "ISO/IEC 9945-1:1996
> LINE("-p1003.1-2001","IEEE Std 1003.1-2001 (\\(LqPOSIX.1\\(Rq)")
> 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", "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)")
> 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 - 1.153
> +++ share/man/man7/mdoc.7 23 Jun 2017 17:04:35 -
> @@ -2588,11 +2588,6 @@ The second and last Technical Corrigendu
> .br
> This standard is also called
> X/Open Portability Guide version 7.
> -.Pp
> -.It \-p1003.1-2013
> -.St -p1003.1-2013
> -.br
> -This is the first Technical Corrigendum.
> .El
> .It Other standards
> .Pp
>
Re: mdoc(7): .St for latest POSIX
Hi Jason,
Jason McIntyre wrote on Thu, Jun 22, 2017 at 02:07:51PM +0100:
> so do you want to remove the entry for 1003.1-2013 as well?
> none of our man pages use it.
The decisive point is that even current groff does not support it,
so deleting it is unlikely to break other's pages.
OK?
Ingo
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.in17 Feb 2015 20:33:44 - 1.22
+++ usr.bin/mandoc/st.in23 Jun 2017 17:04:35 -
@@ -34,7 +34,6 @@ LINE("-p1003.1-96", "ISO/IEC 9945-1:1996
LINE("-p1003.1-2001", "IEEE Std 1003.1-2001 (\\(LqPOSIX.1\\(Rq)")
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", "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)")
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 - 1.153
+++ share/man/man7/mdoc.7 23 Jun 2017 17:04:35 -
@@ -2588,11 +2588,6 @@ The second and last Technical Corrigendu
.br
This standard is also called
X/Open Portability Guide version 7.
-.Pp
-.It \-p1003.1-2013
-.St -p1003.1-2013
-.br
-This is the first Technical Corrigendum.
.El
.It Other standards
.Pp
Re: mdoc(7): .St for latest POSIX
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 - 1.153
> > +++ share/man/man7/mdoc.7 22 Jun 2017 06:20:33 -
> > @@ -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.in17 Feb 2015 20:33:44 - 1.22
> > +++ usr.bin/mandoc/st.in22 Jun 2017 06:20:33 -
> > @@ -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)")
>
Re: mdoc(7): .St for latest POSIX
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 - 1.153
> +++ share/man/man7/mdoc.7 22 Jun 2017 06:20:33 -
> @@ -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 - 1.22
> +++ usr.bin/mandoc/st.in 22 Jun 2017 06:20:33 -
> @@ -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)")
Re: mdoc(7): .St for latest POSIX
On Thu, Jun 22, 2017 at 12:21:55AM -0600, Anthony J. Bentley wrote:
> ok?
>
morning. yes, ok.
jmc
> 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 - 1.153
> +++ share/man/man7/mdoc.7 22 Jun 2017 06:20:33 -
> @@ -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 - 1.22
> +++ usr.bin/mandoc/st.in 22 Jun 2017 06:20:33 -
> @@ -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)")
>
mdoc(7): .St for latest POSIX
ok?
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 - 1.153
+++ share/man/man7/mdoc.7 22 Jun 2017 06:20:33 -
@@ -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.in17 Feb 2015 20:33:44 - 1.22
+++ usr.bin/mandoc/st.in22 Jun 2017 06:20:33 -
@@ -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)")
